|
TReK ANSI-C
5.3.3
All ANSI-C APIs
|
The trek_toolkit_record_device_api library provides ANSI C functions that create, populate, and close record files on both Windows and Red Hat Enterprise Linux operating systems. The record library is configured using a simple text file of name-value pairs.
Background
The TReK Record library provides a record API to control the creation, population and closing of record files. The TReK Record library may be configured to populate the record files using UDP or TCP/IP sockets and close record files automatically based upon their size or based upon the length of time they have been open. In addition, record files may be closed using a primitive directive from a CFDP application.
The library provides the option to automatically move closed record files to an encrypt, frag or CFDP dropbox or generate CFDP transaction requests to transfer the files to predefined destinations. A call back function is also supported to notify a user when a record file is closed.
TReK Record Library
Initialization:
The InitToolkitRecordDevice function initializes the TReK Record library by reading parameters from a TReK Record configuration file to determine if the library is being configured to populate record files using the RecordPacket API function, UDP sockets or TCP/IP sockets. For UDP and TCP/IP support, the InitToolkitRecordDevice function creates and associates a UDP client socket or TCP Listener socket with the path and file name of a record file. The path and filename of a Packet Header Processor (PHP) configuration file may also be identified to provide information about the record packet's header including the location of its size, embedded time and sequence count fields. Unlike UDP sockets, TCP sockets may receive packet segments and not fully assembled packets. An application that receives packets from a TCP socket may receive the packet in multiple segments or it may receive multiple packets in a single segment. To retrieve the packets of data from the segment(s), packets must either be a fixed size or designed with a packet header that at a minimum includes a packet length and/or a packet synchronization pattern. By defining, creating and associating a PHP with a TCP socket, the TReK Record library can retrieve packets from TCP segments. The format of the PHP configuration file is included in this document. The TReK Record library configuration file also provides information about automatically closing record files and moving closed files to encryption, fragmentation or CFDP dropbox directories or instantiating CFDP "put" transaction requests to initiate a CFDP "put" of the the closed record files.
CFDP record library support is optional and only required when working with dropboxes or automating the instantiation of CFDP "put" transactions of record files. The CFDP library device name must be defined in the TReK Record library's configuration file and the CFDP library's configuration file when automating CFDP "put" transactions from the TReK Record library. All record files identified by the TReK Record library configuration file are created and opened during the initialization process.
An application should call the InitToolkitRecordDevice function prior to using any of the TReK Record API functions.
The path and file name of a TReK Record library configuration file are included with the call to the InitToolkitRecordDevice function.
The format of a TReK Record configuration file is a series of name value pairs that configure the library to meet user requirements. One or more spaces separate individual parameters on each line in the file. The following table identifies and describes the configuration file parameters. The TReK Record library ignores parameters in the file that are not relevant to its configuration.
| Record Configuration File Parameter | Description |
| RLD_configuration_version | The configuration file version number. The first parameter in the configuration file must be the version number or TReK Record initialization will fail. |
| record_library_device_name | A unique reference that may be used to communicate with other TReK library devices. |
| log_messages_in_file | The log messages in file boolean controls message logging. If true, messages are recorded in a log file. The default value is false. |
| log_debug_messages | The log debug messages boolean controls logging debug messages. If true, debug messages are recorded in a log file. The default value is false. |
| log_file_path | The log file path is the absolute path to the directory where the log file should be written. If an empty string is provided, the default path is the user's home directory. |
| log_file_name | The log file name is the name to use for the log file. The default value "toolkit_record_log". |
| record_stat_snapshot_in_file | The record stat snapshot in file boolean controls recording statistics. If "true", a statistic snapshot is recorded in a file. The default value is false. |
| record_packet_statistics | The record packet statistics boolean controls recording packet statistics in addition to device statistics. If "true", packet statistics are recorded in a file. The default value is false. |
| record_stat_file_path | The record stat file path is the absolute path to the directory where the statistics file should be recorded. If an empty string is provided, the default path is the user's home directory. |
| record_stat_file_name | The record stat file name is the name to use for the statistics file. The default value is "toolkit_record_statistics". |
| write_buffer_size | Buffer multiple packets up to the write buffer size in bytes prior to making a write call to the file. Zero implies every packet has an associated write call to the file. Minimum value is zero, maximum value is 4,294,967,295 and the default value is 0. |
| max_file_size | Close record file based on the number of bytes recorded in the file and then create a new record file. Minimum value is zero meaning do not close record file based on size, maximum value is 4,294,967,295 and the default value is 0. |
| max_time_file_is_open | Close record file based on the number of minutes the record file is open and then create a new record file. The record file will not be closed if no packets were recorded in the file. Minimum value is zero meaning do not close record file based on time, maximum value is 4,294,967,295 and the default value is 0. |
| create_con_file | The create con file boolean controls the creation of a packet header processor configuration file (.con file) for TReK record file playback. A configuration file may only be created if a PHP was associated with the record file. The configuration file is titled using the unmodified record file name with a ".con" index. A single configuration file is created for each unmodified record file name. The default value is false. |
| single_time_stamp | The single time stamp boolean controls appending a record file name with a single time stamp corresponding to the embedded time stamp of the first packet in the file or if the embedded time is not defined, the open time of the file. If this parameter is false, the record file name is appended with the embedded time of the first and last packet in the file or the open and close time of the file. The default value is true. |
| rec_file_name | Acceptable formats of the rec_file_name primitive string are as follows:
The rec_file_name primitive includes the names and paths of the record files that will be created by the library. The packet header processor configuration file path and name, record file IP address, record file port and protocol are optional and only required when populating the record file using a TCP Listener socket or UDP socket instead of the record API. A UDP socket requires a record file IP address, record file port and protocol. A TCP Listener socket requires a packet header processor configuration file path and name, record file IP address and record file port (the default protocol is TCP and is not required). |
| cfdp_library_device_name | A unique reference that is used to communicate with the TReK CFDP library device. The CFDP library device name was introduced in version 3 of the CFDP configuration file (TReK Release 5.0.0) |
| record_file_transfer | The record file transfer defines the method used to transfer a record file using CFDP. Set to UNDEFINED, implying no CFDP file transfer support, CFDP_DROPBOX or CFDP_DESTINATION. The CFDP_DROPBOX configuration moves a closed record file to a dropbox directory. Note, CFDP_DROPBOX includes all dropbox types created by the CFDP application including encryption and fragmentation dropboxes. The CFDP_DESTINATION configuration delivers a CFDP "put" request to the local CFDP library application when the record file is closed. Only one record file transfer type is supported per record library instance. |
| cfdp_dropbox_path rec_file_name | Move a closed record file to a drop box directory (CFDP, encryption or fragmentation drop box). Only one drop box may be associated with a record file. Supports multiple record file names on a single line and multiple CFDP drop box path entries. cfdp_dropbox_path <"dropbox_path"> rec_file_name <"file_name1"> <"file_name2"> <"file_name3"> |
| put | Initiate a CFDP "put" primitive file transfer from a record directory when the record file is closed. Only one "put" primitive may be associated with a record file. Supports multiple "put" primitive entries. CFDP ION only supports the defaults "/" or "////". put <class1,class2,////> <"record_file_name"> <dest_eid> <"dest_path"> |
The TReK PHP is used by the TReK Record library to retrieve the embedded time from a packet's header and/or build complete packets from TCP packet segments.
The format of a TReK PHP configuration file is a series of name value pairs that configure the PHP to meet user requirements. One or more spaces separate individual parameters on each line in the file. The PHP configuration version number is the only required parameter in the TReK PHP configuration file, all other parameters are optional. The following table identifies and describes the configuration file parameters.
| PHP Configuration File Parameter | Description |
| PHP_configuration_version | The configuration file version number. The first parameter in the configuration file must be the version number. The current value is set to 1. |
| fixed_packet_size | Define a fixed packet size for all packets and ignores the packet size parameter location. A value of zero implies the packets are not a fixed size. The default value is 0. |
| packet_size_field byte_offset bit_offset bit_length byte_order packet_size_offset | The packet size field defines the location and format of the packet size parameter. All byte and bit offsets start at zero and are numbered from from left to right and may be up to 32 bits in length. Byte order is set to BIG_ENDIAN or LITTLE_ENDIAN. The packet size offset is added to the packet size prior to calculating the total size of the packet. The default value for all fields is 0. |
| sequence_count_field byte_offset bit_offset bit_length byte_order | The sequence count field defines the location and format of the sequence count parameter. All byte and bit offsets start at zero and are numbered from from left to right and may be up to 32 bits in length. Byte order is set to BIG_ENDIAN or LITTLE_ENDIAN. The default value for all fields is 0. |
| embedded_time_type | The embedded time type defines the epoch that should be used when calculating the embedded time. Set to UNDEFINED, implying no embedded time, UNIX_POSIX or GPS. The UNIX_POSIX configuration defines the epoch as midnight GMT January 1, 1970. The GPS configuration defines the epoch as midnight GMT January 6, 1980. Only one embedded time may be defined per PHP instance. The default value is UNDEFINED. |
| sec_time_field byte_offset bit_offset bit_length byte_order | The second time field defines the location and format of the second time parameter. All byte and bit offsets start at zero and are numbered from from left to right and may be up to 32 bits in length. Byte order is set to BIG_ENDIAN or LITTLE_ENDIAN. The default value for all fields is 0. |
| milli_time_field byte_offset bit_offset bit_length byte_order milli_time_precision | The millisecond time field defines the location and format of the millisecond time parameter. All byte and bit offsets start at zero and are numbered from from left to right and may be up to 32 bits in length. Byte order is set to BIG_ENDIAN or LITTLE_ENDIAN. The millisecond time parameter is multiplied by the milli time precision value when calculating the millisecond time of the packet. The default value for all fields is 0 or 1.0. |
| micro_time_field byte_offset bit_offset bit_length byte_order micro_time_precision | The microsecond time field defines the location and format of the microsecond time parameter. All byte and bit offsets start at zero and are numbered from from left to right and may be up to 32 bits in length. Byte order is set to BIG_ENDIAN or LITTLE_ENDIAN. The microsecond time parameter is multiplied by the micro time precision value when calculating the microsecond time of the packet. The default value for all fields is 0 or 1.0. |
| sync_pattern_begins_packet | The sync pattern begins packet boolean identifies the presence of a synchronization pattern at the beginning of a packet. The default value is false. |
| sync_pattern_ends_packet | The sync pattern ends packet boolean identifies the presence of a synchronization pattern at the end of a packet. The default value is false. |
| sync_hex_pattern | A hexadecimal value defining one to sixteen synchronization bytes found at the beginning or end of a packet (e.g., ffaabb66 or FFAABB66). The default value is an empty string |
| packet_type | The packet type is a user defined character string parameter in a packet key. A packet key is an alphanumeric dotted string notation of one or more packet key field values (packet header parameters) and zero or more character strings formatted as follows: <packet type>.<packet header field value(s)>.<source ID>.<trailer> (e.g., 1.2.3, CCSDS.1.2.3.4., CCSDS.1.2.PB,...). The default value for packet type is an empty string. |
| packet_key_field byte_offset bit_offset bit_length byte_order wild_card | The packet key field defines the location and format of a packet header field parameter. All packet key fields must include a unique field name for proper identification. All byte and bit offsets start at zero and are numbered from from left to right and may be up to 32 bits in length Byte order is set to BIG_ENDIAN or LITTLE_ENDIAN (e.g., packet_key_field "CP=APID" byte_offset 28 bit_offset 5 bit_length 11 byte_order BIG_ENDIAN wild_card false). The wild card boolean controls whether a field is represented by an "*" in the packet key calculation. A wild card field may be useful when using the packet key to define which packets should be sent to a TReK device. Packet key header parameters are ordered in the packet key according to the order they were defined in the configuration file. All enumerator values associated with the packet header key parameter must be listed immediately after after the packet key field description. The default value for all fields is 0 or false. |
| enum_value enum_name | The enum value and enum name defines an enumerator value and its associated name for the a packet header key field. Multiple enum value and enum name pairs may be defined for a packet key field but they must be listed immediately after the packet key field definition (e.g., enum_value 1 enum_name RT). The enum_name will replace the enum value in the generation of a packet key. |
| source_ID | The source ID is a user defined character string parameter in a packet key. If defined, the source ID immediately follows the last packet header field parameter. <packet type>.<packet header field value(s)>.<source ID>.<trailer>. The default value for the source ID is an empty string. |
| packet_key_trailer | The packet key trailer is a user defined character string parameter in a packet key. If defined, the packet key trailer added to the end of the packet key. <packet type>.<packet header field value(s)>.<source ID>.<trailer>. The default value for the packet key trailer is an empty string. |
| record_file_format | The record file format defines the format of a TReK record file that may be associated with this PHP configuration file. The record file format is used by TReK when reading/playing back a record file. Set to UNDEFINED or TREK_RELEASE_3 (note, TREK_RELEASE_3 is currently not supported). The default value is UNDEFINED. |
| packet_key_history | The packet key history defines all the packet keys present in a TReK record file that may be associated with this PHP configuration file. The default value is an empty string. |
Packet Recording:
The TReK Record library provides the RecordPacket function to record packets in a record file identified by the record file name. The record file name must be defined in the TReK Record library configuration file.
Closing Record Files:
The TReK Record library provides two functions to close a record file, CloseRecordFile and CloseAllRecordFiles. The CloseRecordFile function closes a record file identified by the record file name, renames the file by appending a time stamp to the name and immediately opens a new record file. The closed record file's new time stamped file name is returned when the function completes. If the record file is associated with a PHP configuration file that defines an embedded time field, the embedded time of the first packet is used in the time stamped record file name instead of the record file's create/open time. If the TReK Record library is configured to use two times when renaming the closed record file the embedded time of the first and last packet in the file are used in the time stamp name, otherwise the record file's open and close times are used in the time stamp name. If the closed record file has not recorded any packets, it is deleted and the time tagged name that is returned is an empty string. If the TReK Record library is configured to interface with a CFDP dropbox, the closed record file is moved to the CFDP dropbox directory. If the TReK Record library is configured to issue a CFDP "put" primitive, the library sends a CFDP "put" transaction request to a CFDP application identified by the CFDP application's library device name. The CloseAllRecordFiles closes all currently open record files, renames the closed files with the appropriate time stamp, interfaces with CFDP as defined in the configuration file and creates/opens new record files. The TReK Record library also provides a method to register a callback function when a record file is closed. The user must register their callback function using the RegisterRecordDeviceData function. The callback function returns the new time appended record file name and the number of packets recorded in the file inside a message structure defined as follows:
| Data Type | Member Variable Name | Description |
| unsigned long | ds_message_code | An unsigned integer defined in ds_shared.h describing the message (e.g., DS_CLOSE = 4) |
| char | record_library_device_name | The name of the record library that closed the record file |
| char | record_file_base_name | The closed record file name without the time stamp |
| char | record_file_pathname | The path and time appended record file name of the closed record file |
| char | packet_count | The number of packets recorded in the closed record file |
| char | max_packet_sequence_error | The maximum packet sequence error of the recorded packets if the packets contain a sequence count |
Final Notes
The TReK Record library is thread safe. Call the DSCleanUp function prior to exiting to gracefully shut down and properly clean up the TReK Record library. Be sure to look at the examples provided with this library for a better understanding on how to use the library functions.
Click on this link toolkit_record_device_api_ansi_c.h to go to the header file with all the functions.
Functions from other APIs
RegisterMessage
DSCleanUp
GetMessageCategoryAsString
Examples
The following examples are provided to show how to use the TReK Record library functions:
Record packets using API and initiate CFDP "put" primitives
Shows how to records four packets in two different record files using the InitToolkitRecordDevice and RecordPacket function. The record library initiates two CFDP "put" primitive when the two record files are closed using the CloseRecordFile function.
Source File:
record_api/main.c
Configuration Files:
record_api/record_api_config.txt
record_api/record_api_php_config.txt
Record packets using TCP and move closed files to a CFDP dropbox directory
Shows how to records four packets in two different record files using the InitToolkitRecordDevice and two TCP Listener sockets. The record library moves the two record files to a simulated CFDP dropbox directory when the two record files are closed using the CloseAllRecordFiles function.
Source File:
record_tcp/main.c
Configuration Files:
record_tcp/record_tcp_config.txt
record_tcp/record_tcp_php_config.txt
Record packets using UDP and move closed files to a CFDP dropbox directory
Shows how to records four packets in two different record files using the InitToolkitRecordDevice and two UDP unicast sockets. The record library moves the two record files to a simulated CFDP dropbox directory when the two record files are closed using the CloseAllRecordFiles function.
Source File:
record_udp/main.c
Configuration Files:
record_udp/record_udp_config.txt
record_udp/record_udp_php_config.txt
Additional Dependencies
The TReK Record Library API is also dependent on the following libraries.
trek_toolkit_common_api
trek_toolkit_ds_api
trek_toolkit_record_device_api
trek_record_device