toolkit_ds_api_ansi_c.h File Reference

An ANSI C Data Service API. More...

#include "ds_shared.h"
#include "trek_toolkit_common_api_ansi_c.h"
#include "bp_shared.h"

Functions
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateUnicastUDPSocketDevice (const char *ip_address, unsigned short port, unsigned int receive_queue_size, unsigned int receive_buffer_size, unsigned int *device_key_buffer_size_ptr, char *device_key)
	Creates a UDP socket to send and receive packets at the specified IP address and port. UDP protocal does not guarantee delivery of the packet or packets being received in the order they were sent. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateUnixLocalClientSocketDevice (const char *name, unsigned int receive_queue_size, unsigned int receive_buffer_size, unsigned int *device_key_buffer_size_ptr, char *device_key)
	Creates a Unix local client socket for interprocess communication on a Linux operating system using a unique name and an abstract name space. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateIPv4MulticastUDPSocketDevice (unsigned short port, unsigned int receive_queue_size, unsigned int receive_buffer_size, boolean_type disable_loopback_flag, unsigned int *device_key_buffer_size_ptr, char *device_key)
	Creates a UDP socket to send and receive IP version 4 multicast packets at the specified port. UDP protocal does not guarantee delivery of the packet or packets being received in the order they were sent. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateTCPListenerSocketDevice (const char *ip_address, unsigned short port, unsigned int receive_queue_size, unsigned int receive_buffer_size, unsigned int *device_key_buffer_size_ptr, char *device_key)
	Creates a TCP listener socket. The listener socket accepts and connects client sockets to newly created server sockets. TCP protocal guarantees delivery of the packets in the order they were sent although it may break the packets up into segments that must be reassembled by the receiving application. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateTCPClientSocketDevice (const char *ip_address, unsigned short port, unsigned int receive_queue_size, unsigned int receive_buffer_size, unsigned int *device_key_buffer_size_ptr, char *device_key)
	Creates a TCP client socket. The client socket must make a separate connection request to a TCP listener sockets and connect to the listener's server socket. TCP protocal guarantees delivery of the packets in the order they were sent although it may break the packets up into segments that must be reassembled by the receiving application. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateBPDevice (unsigned int source_service_number, unsigned int lifespan, bp_class_of_service_type cos, unsigned int ordinal, bp_transmission_mode_type mode, bp_criticality_type criticality, unsigned int *device_key_buffer_size_ptr, char *device_key)
	Creates a Bundle Protocol (BP) device that attaches to ION's BP library. ION's BP application must be running prior to creating the BP device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	CreateDeviceKeyAlias (const char *device_key, const char *device_key_alias)
	Create a user friendly name/alias and associate it with a device key. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	ConnectSocketDevice (const char *device_key, const char *ip_address_to_connect_to, unsigned short port_to_connect_to, unsigned int connection_timeout_msec)
	Connect a TCP client socket to a TCP listener's server socket. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	JoinMulticastGroup (const char *ip_address, const char *multicast_group_address, const char *device_key)
	Associates a mulitcast socket with a multicast group address. A multicast socket must join a multicast group by calling JoinMulticastGroup prior to receiving packets sent to the IP multicast group address. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	SetMulticastTTL (const char *device_key, unsigned short multicast_ttl)
	Sets the time to live for a socket that is sending packets to a multicast address. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	SetTCPKeepalive (const char *device_key, unsigned long keepalive_time, unsigned long keepalive_interval, unsigned long keepalive_probes)
	Sets the TCP keepalive parameters to determine whether the TCP connection is still up and running or has broken. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DeleteDevice (const char *device_key)
	Decrements the device's use counter and if the device use counter is zero, all reference to the device are deleted and all device resources are released. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	ReceivePacketFromDevice (const char *device_key, unsigned int receive_timeout, unsigned int *packet_buffer_size_ptr, int *packet_length_ptr, unsigned char *packet_buffer_ptr, unsigned int *message_code_ptr)
	Receive a packet from a device within a specified time period. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	ReceivePacketFromSocketDevice (const char *device_key, unsigned int receive_timeout, unsigned int *packet_buffer_size_ptr, int *packet_length_ptr, unsigned char *packet_buffer_ptr, unsigned int *message_code_ptr, unsigned int *receive_from_ip_address_buffer_size_ptr, char *received_from_ip_address, unsigned short *received_from_port_ptr)
	Receive a packet from a socket device within a specified time period. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	SendPacket (const char *device_key, int packet_length, unsigned char *packet_buffer_ptr)
	Sends a packet to a device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	SendPacketFromTCPServerSocketDevice (const char *listener_device_key, const char *server_device_key, int packet_length, unsigned char *packet_buffer_ptr)
	Sends a packet from a TCP server socket device to the connected client socket device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	SendPacketFromUDPSocketDevice (const char *device_key, int packet_length, unsigned char *packet_buffer_ptr, const char *send_to_ip_address, unsigned short send_to_port)
	Sends a packet from UDP socket device to the IP address and port number of a corresponding UDP socket device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	SendPacketFromBPDevice (const char *device_key, int packet_length, unsigned char *packet_buffer_ptr, long long destination_node_number, unsigned int destination_service_number)
	Sends a packet from a bundle protocol device to the destination node. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DefinePHPPacketSizeField (const char *php_name, unsigned int byte_offset, unsigned int bit_offset, unsigned int length_in_bits, long size_offset_value, endian_byte_order byte_order)
	Defines the location of a packet size field in a new or existing packet header. All byte and bit offsets start at zero and are numbered from from left to right. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DefinePHPSyncHexPattern (const char *php_name, const char *sync_hex_pattern, boolean_type start_of_packet_sync_flag)
	Defines a synch pattern for packets that require synchronization in a new or existing packet header processor. The sync pattern is described in hexadecimal format. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DefinePHPFixedPacketSize (const char *php_name, unsigned int fixed_packet_size)
	Defines the size of all the packets that will be recieved by a device that is associated with this new or existing packet header processor. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DefinePHPPacketSequenceCountField (const char *php_name, unsigned int byte_offset, unsigned int bit_offset, unsigned int length_in_bits, endian_byte_order byte_order)
	Defines the location of a packet sequence count in a new or existing packet header. All byte and bit offsets start at zero and are numbered from from left to right. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DefinePHPPacketKeyField (const char *php_name, const char *packet_key_name, unsigned int byte_offset, unsigned int bit_offset, unsigned int length_in_bits, endian_byte_order byte_order)
	Defines the location of a packet key field in a new or existing packet header. All byte and bit offsets start at zero and are numbered from from left to right. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	AddPacketHeaderProcessor (const char *php_name, const char *device_key)
	Adds or associates an existing packet header processor with a device to support retreiving packets from packet segments or deterimining packets statistics. Only one uniquely defined packet header processor may be added to a device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	GeneratePublicPrivateKeyPair (const char *public_key_pathname, const char *private_key_pathname)
	Generates a public/private key pair based on Elliptic Curve Cryptography (ECC) using curve P-256. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	GeneratePublicPrivateKeyPairWithPassphrase (const char *public_key_pathname, const char *private_key_pathname, const char *crypt_user_passphrase)
	Generates a public/private key pair based on Elliptic Curve Cryptography (ECC) using curve P-256. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	AddCipherToDevice (const char *device_key, cipher_class_type cipher_class, const char *public_key_pathname, const char *private_key_pathname, const char *peer_public_key_pathname, int pkt_key_encrypt_time_interval_sec, const char *crypt_user_passphrase)
	The AddCipherToDevice function encrypts all data being sent by a device and decrypts all data prior to being processed by a device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	AddCipherToDeviceWithPeerIPAddress (const char *device_key, cipher_class_type cipher_class, const char *public_key_pathname, const char *private_key_pathname, const char *peer_public_key_pathname, int pkt_key_encrypt_time_interval_sec, const char *peer_ip_address, const char *crypt_user_passphrase)
	The AddCipherToDeviceWithPeerIPAddress function encrypts all data being sent by a device to the peer IP address and decrypts all data received by device from the peer IP address. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	AddCipherToDeviceWithPeerBPNodeNumber (const char *device_key, cipher_class_type cipher_class, const char *public_key_pathname, const char *private_key_pathname, const char *peer_public_key_pathname, int bundle_key_encrypt_time_interval_sec, unsigned int peer_bp_node_number, const char *crypt_user_passphrase)
	The AddCipherToDeviceWithPeerBPNodeNumber function encrypts all data being sent by a device to the peer BP node number and decrypts all data received by device from the peer BP node number. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	StartLoggingMessages (const char *log_file_path, const char *log_filename, boolean_type log_debug_messages)
	Starts logging messages to a file. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	LogMessage (enum message_category category, const char *message)
	Logs a user message in the log file. The maximum null terminated message size is 512 bytes. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	StopLoggingMessages ()
	Stops logging messages to a file, closes the log file and renames the log file by concatenating the log file name with a GMT time string. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	StopLoggingMessagesEx (char *time_tagged_log_file_name)
	Stops logging messages to a file, closes the log file and renames the log file by concatenating the log file name with a GMT time string and returns the new file name. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	StartRecordingStatSnapshot (const char *record_file_path, const char *record_filename, boolean_type record_packet_statistics_flag)
	Starts recording a snapshot of the current statistics to a file. More...
void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	StopRecordingStatSnapshot ()
	Stops recording statisitics to a file, closes the record file and renames the record file by concatenating the record file name with a GMT time string. More...
void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	ResetStatistics ()
	Resets or zero's the device and packet statistics. More...
void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	PopulateIPAddressStructArray (unsigned int *number_of_ip_address_structs_ptr, ip_address_struct_type **ip_address_struct_array_ptr)
	Populates an array of ip_address_struct with the valid IP addresses of the host platform. More...
void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	FreeIPAddressStructArrayMemoryAlloc (ip_address_struct_type *ip_address_struct_array_ptr)
	Frees the memory associated with the ip_address_struct_array_ptr that was returned by PopulateIPAddressStructArray. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	DSCleanUp ()
	Initiates a graceful shutdown of the Device Service library and all supporting device libraries, exits threads, and deallocates memory. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	RegisterMessage (void(*function_ptr)(message_struct_type *message_struct_ptr))
	Register a callback function to receive and process messages issued by the DS library. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	RegisterReceivePacket (const char *device_key, void(*function_ptr)(const char *key, int packet_length, unsigned char *packet_buffer_ptr))
	Register a callback function to receive packets from a device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	RegisterReceivePacketFromSocket (const char *device_key, void(*function_ptr)(const char *device_key, int packet_length, unsigned char *packet_buffer_ptr, const char *received_from_ip_address, unsigned short received_from_port))
	Register a callback function to receive packets from a socket device. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	RegisterAcceptConnection (const char *listener_device_key, int(*function_ptr)(const char *listener_device_key, const char *server_device_key, const char *connected_ip_address, unsigned short connected_port))
	Register a callback function to accept a connection request from a client socket. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	RegisterDropConnectionFromListener (const char *listener_device_key, void(*function_ptr)(const char *listener_device_key, const char *disconnected_server_device_key, const char *disconnected_remote_ip_address, unsigned short disconnected_remote_port))
	Register a callback function to receive notification of a dropped connection when a listener's server socket connection is dropped by its client. More...
int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION	RegisterDropConnectionFromClient (const char *client_device_key, void(*function_ptr)(const char *disconnected_client_device_key, const char *disconnected_remote_ip_address, unsigned short disconnected_remote_port))
	Register a callback function to receive notification of a dropped connection when a client socket connection is dropped by its server. More...

Detailed Description

An ANSI C Data Service API.

Function Documentation

AddCipherToDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION AddCipherToDevice	(	const char *	device_key,
		cipher_class_type	cipher_class,
		const char *	public_key_pathname,
		const char *	private_key_pathname,
		const char *	peer_public_key_pathname,
		int	pkt_key_encrypt_time_interval_sec,
		const char *	crypt_user_passphrase
	)

The AddCipherToDevice function encrypts all data being sent by a device and decrypts all data prior to being processed by a device.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	cipher_class	The cipher package that the TReK encryption library will use to encrypt and decrypt data. The cyphers support either a 128 bit or 256 bit symmetric key. The cipher_class_type is defined in the file "ds_shared.h" as follows: cipher_class_type AES_128_GCM AES_256_GCM AES_128_CCM AES_256_CCM
[in]	public_key_pathname	The path and file name of the public key.
[in]	private_key_pathname	The path and file name of the private key.
[in]	peer_public_key_pathname	The path and file name of the peer public key. The peer public key is the public key of the remote/destination platform.
[in]	pkt_key_encrypt_time_interval_sec	Determines how often the packet encryption key is changed while encrypting a stream of packets. If the packet encryption key time interval is set to zero, the TReK encryption library will generate a new packet encryption key for every packet in the stream.
[in]	crypt_user_passphrase	The passphrase that is used to wrap/encrypt the private key prior to storing the key in the private key file. Pass an empty string (i.e., "") if no crypt_user_passphrase was defined when the public/private key pair was created.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_INVALID_DEVICE_TYPE

DS_DEVICE_HAS_EXISTING_CIPHER

Example:

char ip_address[50];
char socket_device_key[100];
char public_key_pathname[50];
char private_key_pathname[50];
char peer_public_key_pathname[50];
char user_passphrase[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
cipher_class_type cipher_class = AES_128_GCM;
int pkt_key_encrypt_time_interval_sec = 10;
 
 
strcpy(public_key_pathname,"/home/user/public.key");
strcpy(private_key_pathname,"/home/user/private.key")
strcpy(peer_key_pathname,"/home/user/peer.key")
strcpy(user_passphrase,"");  // No passphrase was used when wrapping/encrypting private key (i.e., used GeneratePublicPrivateKeyPair function to create public/private key pair)
 
strcpy(ip_address,"128.128.128.128");  
if (CreateUnicastUDPSocketDevice(ip_address,
    source_port,
    receive_queue_size,
    receive_buffer_size,
    &key_buffer_size,
    socket_device_key) == SUCCESS)
{
    if (AddCipherToDevice(socket_device_key,
                          cipher_class,
                          public_key_pathname,
                          private_key_pathname,
                          peer_public_key_pathname,
                          pkt_key_encrypt_time_interval_sec,
                          user_passphrase) != SUCCESS)
    {                 
        DSCleanUp();
        return 1;                 
    }
}

Examples

network_bp_source_encrypt_decrypt/main.c, and network_encrypt_decrypt/main.c.

AddCipherToDeviceWithPeerBPNodeNumber()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION AddCipherToDeviceWithPeerBPNodeNumber	(	const char *	device_key,
		cipher_class_type	cipher_class,
		const char *	public_key_pathname,
		const char *	private_key_pathname,
		const char *	peer_public_key_pathname,
		int	bundle_key_encrypt_time_interval_sec,
		unsigned int	peer_bp_node_number,
		const char *	crypt_user_passphrase
	)

The AddCipherToDeviceWithPeerBPNodeNumber function encrypts all data being sent by a device to the peer BP node number and decrypts all data received by device from the peer BP node number.

The peer public key is the public key of the remote/destination platform. The peer BP node number is the DTN ION node number of the remote/destination platform. If the data is sent to or received from a BP node number that does not match the peer BP node number, the device will not encrypt the sent data or decrypt the received data.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	cipher_class	The cipher package that the TReK encryption library will use to encrypt and decrypt data. The cyphers support either a 128 bit or 256 bit symmetric key. The cipher_class_type is defined in the file "ds_shared.h" as follows: cipher_class_type AES_128_GCM AES_256_GCM AES_128_CCM AES_256_CCM
[in]	public_key_pathname	The path and file name of the public key.
[in]	private_key_pathname	The path and file name of the private key.
[in]	peer_public_key_pathname	The path and file name of the peer public key. The peer public key is the public key of the remote/destination platform.
[in]	bundle_key_encrypt_time_interval_sec	Determines how often the bundle encryption key is changed while encrypting a stream of bundles. If the bundle encryption key time interval is set to zero, the TReK encryption library will generate a new bundle encryption key for every bundle in the stream.
[in]	peer_bp_node_number	The DTN ION node number of the remote/destination platform that is receiving the encrypted data or sending the encrypted data (i.e., the DTN ION node number of the remote/destination platform whose public key is represented by the peer public key).
[in]	crypt_user_passphrase	The passphrase that is used to wrap/encrypt the private key prior to storing the key in the private key file. Pass an empty string (i.e., "") if no crypt_user_passphrase was defined when the public/private key pair was created.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_INVALID_DEVICE_TYPE

DS_DEVICE_HAS_EXISTING_CIPHER

Example:

int  return_value;
char bp_device_key[100];
char public_key_pathname[50];
char private_key_pathname[50];
char peer_public_key_pathname[50];
char user_passphrase[50];
unsigned int source_service_number;
unsigned int lifespan;
bp_class_of_service_type cos;
unsigned int ordinal;
bp_transmission_mode_type mode;
bp_criticality_type criticality;
unsigned int key_buffer_size = 100;
cipher_class_type cipher_class = AES_256_GCM;
int bundle_key_encrypt_time_interval_sec = 10;
unsigned int peer_bp_node_number = 33333;
strcpy(public_key_pathname,"/home/user/public.key");
strcpy(private_key_pathname,"/home/user/private.key")
strcpy(peer_key_pathname,"/home/user/peer.key")
strcpy(user_passphrase,"qwert12345!");
source_service_number = 3;
lifespan = 86400;
cos = BPD_STD_PRIORITY;
ordinal = 0;
mode = BPD_ASSURED;
criticality = BPD_NOT_CRITICAL;
 
if (CreateBPDevice( source_service_number,
                    lifespan,
                    cos,
                    ordinal,
                    mode,
                    criticality,
                    &key_buffer_size,
                    bp_device_key) == SUCCESS)
{
    if (AddCipherToDeviceWithPeerBPNodeNumber(  bp_device_key,
                                                cipher_class,
                                                public_key_pathname,
                                                private_key_pathname,
                                                peer_public_key_pathname,
                                                bundle_key_encrypt_time_interval_sec,
                                                peer_bp_node_number,
                                                user_passphrase) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_bp_destination_encrypt_decrypt/main.c.

AddCipherToDeviceWithPeerIPAddress()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION AddCipherToDeviceWithPeerIPAddress	(	const char *	device_key,
		cipher_class_type	cipher_class,
		const char *	public_key_pathname,
		const char *	private_key_pathname,
		const char *	peer_public_key_pathname,
		int	pkt_key_encrypt_time_interval_sec,
		const char *	peer_ip_address,
		const char *	crypt_user_passphrase
	)

The AddCipherToDeviceWithPeerIPAddress function encrypts all data being sent by a device to the peer IP address and decrypts all data received by device from the peer IP address.

The peer public key is the public key of the remote/destination platform. The peer IP address is the IP address of the remote/destination platform. If the data is sent to or received from an IP address that does not match the peer IP address, the device will not encrypt the sent data or decrypt the received data.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	cipher_class	The cipher package that the TReK encryption library will use to encrypt and decrypt data. The cyphers support either a 128 bit or 256 bit symmetric key. The cipher_class_type is defined in the file "ds_shared.h" as follows: cipher_class_type AES_128_GCM AES_256_GCM AES_128_CCM AES_256_CCM
[in]	public_key_pathname	The path and file name of the public key.
[in]	private_key_pathname	The path and file name of the private key.
[in]	peer_public_key_pathname	The path and file name of the peer public key. The peer public key is the public key of the remote/destination platform.
[in]	pkt_key_encrypt_time_interval_sec	Determines how often the packet encryption key is changed while encrypting a stream of packets. If the packet encryption key time interval is set to zero, the TReK encryption library will generate a new packet encryption key for every packet in the stream.
[in]	peer_ip_address	The IP address of the remote/destination platform that is receiving the encrypted data or sending the encrypted data (i.e., the IP address of the remote/destination platform whose public key is represented by the peer public key).
[in]	crypt_user_passphrase	The passphrase that is used to wrap/encrypt the private key prior to storing the key in the private key file. Pass an empty string (i.e., "") if no crypt_user_passphrase was defined when the public/private key pair was created.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_INVALID_DEVICE_TYPE

DS_DEVICE_HAS_EXISTING_CIPHER

Example:

char ip_address[50];
char socket_device_key[100];
char public_key_pathname[50];
char private_key_pathname[50];
char peer_public_key_pathname[50];
char peer_ip_address[50];
char user_passphrase[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
cipher_class_type cipher_class = AES_128_GCM;
int pkt_key_encrypt_time_interval_sec = 10;
strcpy(public_key_pathname,"/home/user/public.key");
strcpy(private_key_pathname,"/home/user/private.key")
strcpy(peer_key_pathname,"/home/user/peer.key")
strcpy(user_passphrase,"");  // No passphrase was used when wrapping/encrypting private key (i.e., used GeneratePublicPrivateKeyPair function to create public/private key pair)
strcpy(ip_address,"128.128.128.128");
strcpy(peer_ip_address,"129.3.4.5");
 
if (CreateUnicastUDPSocketDevice(ip_address,
    source_port,
    receive_queue_size,
    receive_buffer_size,
    &key_buffer_size,
    socket_device_key) == SUCCESS)
{
    if (AddCipherToDeviceWithPeerIPAddress( socket_device_key,
                                            cipher_class,
                                            public_key_pathname,
                                            private_key_pathname,
                                            peer_public_key_pathname,
                                            pkt_key_encrypt_time_interval_sec,
                                            peer_ip_address,
                                            user_passphrase) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_encrypt_decrypt/main.c.

AddPacketHeaderProcessor()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION AddPacketHeaderProcessor	(	const char *	php_name,
		const char *	device_key
	)

Adds or associates an existing packet header processor with a device to support retreiving packets from packet segments or deterimining packets statistics. Only one uniquely defined packet header processor may be added to a device.

If a TCP socket device is receiving packets the protocol may group or divide packets into segments which must be processed to retrieve inidividual packets.
If each packet has a predefined header with a packet size parameter, then the packets may be retrieved from the segments by defining the location of the packet size parameter using the DefinePHPPacketSizeField function or packets may be retrieved by defining a packet sync pattern using the DefinePHPSyncHexPattern function or by defining both a size field and sync hex pattern using the same packet header processor name in the DefinePHPPacketSizeField and DefinePHPSyncHexPattern functions. If the TCP socket does not have an associated packet header processor, it can only provide packet segments and not complete packets to the user. Packet statistics may be gathered by using the DefinePHPPacketKeyField function and the DefinePHPPacketSequenceCountField function.

Parameters

[in]	php_name	A user friendly name for the packet header processor.
[in]	device_key	A character string that uniquely identifies each device.

Returns

SUCCESS

DS_PHP_NOT_DEFINED

DS_DEVICE_HAS_EXISTING_PHP

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
char php_name[50];
char source_device_key[100];
unsigned short source_port = 6300;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
unsigned int byte_offset = 1;
unsigned int bit_offset = 4;
unsigned int length_in_bits  = 20;
long size_offset_value = 0;
endian_byte_order byte_order = BIG_ENDIAN_ORDER;
strcpy(ip_address,"127.0.0.1"); 
strcpy(php_name,"dr_php");
if (CreateTCPListenerSocketDevice(ip_address,
                                  source_port,
                                  receive_queue_size,
                                  receive_buffer_size,
                                  &key_buffer_size,
                                  source_device_key) == SUCCESS)
{
    if (DefinePHPPacketSizeField(php_name,
                                 byte_offset,
                                 bit_offset,
                                 length_in_bits,
                                 size_offset_value,
                                 byte_order) == SUCCESS)
    {
        if (AddPacketHeaderProcessor(php_name,
                                     source_device_key)!= SUCCESS)
        {
            DSCleanUp();
            return 1;
        }
    }
}

Examples

network_tcp/main.c.

ConnectSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION ConnectSocketDevice	(	const char *	device_key,
		const char *	ip_address_to_connect_to,
		unsigned short	port_to_connect_to,
		unsigned int	connection_timeout_msec
	)

Connect a TCP client socket to a TCP listener's server socket.

Note

This library does not support connecting UDP sockets.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	ip_address_to_connect_to	A character string containing the IP address of the socket that will accept the connection request.
[in]	port_to_connect_to	The port number of the the socket that will accept the connection request.
[in]	connection_timeout_msec	The length of time to wait for a connection to complete (2000 milli-seconds is an appropriate default value).

Returns

SUCCESS

DS_SOCKET_CONNECTION_ERROR

DS_SOCKET_CONNECTION_TIMEOUT_ERROR

DS_INVALID_DEVICE_TYPE

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short listener_port = 6300;
unsigned short client_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
unsigned  int  connection_timeout_msec = 2000;
char listener_device_key[100];
char client_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateTCPListenerSocketDevice(ip_address,
                                  listener_port,
                                  receive_queue_size,
                                  receive_buffer_size,
                                  &key_buffer_size,
                                  listener_device_key) == SUCCESS)
{
    if (CreateTCPClientSocketDevice(ip_address,
                                    client_port,
                                    receive_queue_size,
                                    receive_buffer_size,
                                    &key_buffer_size,
                                    client_device_key) == SUCCESS)
    {
        if (ConnectSocketDevice(client_device_key,
                                ip_address,listener_port,
                                connection_timeout_msec) != SUCCESS)
        {
            DSCleanUp();
            return 1;
        }
    }
}

Examples

network_tcp/main.c, and record_tcp/main.c.

CreateBPDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateBPDevice	(	unsigned int	source_service_number,
		unsigned int	lifespan,
		bp_class_of_service_type	cos,
		unsigned int	ordinal,
		bp_transmission_mode_type	mode,
		bp_criticality_type	criticality,
		unsigned int *	device_key_buffer_size_ptr,
		char *	device_key
	)

Creates a Bundle Protocol (BP) device that attaches to ION's BP library. ION's BP application must be running prior to creating the BP device.

Parameters

[in]	source_service_number	The unsigned integer value service number that associates the device with ION's configured BP service.
[in]	lifespan	The bundle's time to live.
[in]	cos	The BP class of service priority. The bp_class_of_service_type is defined in the file "bp_shared.h" as follows: BP Service Class bp_class_of_service_type Lowest Priority Bundle Transfer BPD_BULK_PRIORITY Standard Priority Bundle Transfer BPD_STD_PRIORITY Highest Priority Bundle Transfer BPD_EXPEDITED_PRIORITY
[in]	ordinal	Only valid for expedited priority bundle transfer. Range from 0-254 with 254 as highest priority
[in]	mode	The BP transmission mode. The bp_transmission_mode_type is defined in the file "bp_shared.h" as follows: BP Transmission Mode bp_transmission_mode_type Delivery Guaranteed by Convergence Layer Protocol BPD_BEST_EFFORT Delivery Guaranteed by BP Layer Protocol BPD_ASSURED Delivery Guaranteed by BP Custody Transfer BPD_ASSURED_WITH_CUSTODY_TRANSFER
[in]	criticality	The BP cricality. The bp_criticality_type is defined in the file "bp_shared.h" as follows: BP Criticality bp_criticality_type Not Critical BPD_NOT_CRITICAL Critical BPD_CRITICAL
[in,out]	device_key_buffer_size_ptr	The size of the buffer that will hold the device key character string. Set to MAX_DEVICE_KEY_SIZE of 100 bytes.
[out]	device_key	A character string that uniquely identifies each device.

Note

Critical or minimum latency requires contact graph routing and no custody transfer. Also, if the device_key buffer is not large enough to hold the new device key then DS_DEVICE_KEY_BUFFER_SIZE_ERROR is returned and device_key_buffer_size is updated with correct value for the device key buffer. The user may use the updated device_key_buffer_size value to preallocate the additional bytes in the device_key prior to calling CreateBPDevice a second time.

Returns

SUCCESS

FAIL

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_DEVICE_KEY_BUFFER_SIZE_ERROR

DS_NULL_POINTER_ERROR

DS_INVALID_BP_CLASS_OF_SERVICE

DS_INVALID_BP_TRANSMISSION_MODE

Example:

int  return_value;
unsigned int source_service_number;
unsigned int lifespan;
bp_class_of_service_type cos;                   
unsigned int ordinal;           
bp_transmission_mode_type mode;             
bp_criticality_type criticality;
unsigned int key_buffer_size = 100;
char source_device_key[100];
 
source_service_number = 3;
lifespan = 86400;
cos = BPD_STD_PRIORITY;             
ordinal = 0;                
mode = BPD_ASSURED;
criticality = BPD_NOT_CRITICAL;
 
if (CreateBPDevice( source_service_number,
                    lifespan,
                    cos,
                    ordinal,
                    mode,
                    criticality,
                    &key_buffer_size,
                    source_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_bp_destination/main.c, network_bp_destination_encrypt_decrypt/main.c, network_bp_polling/main.c, network_bp_source/main.c, and network_bp_source_encrypt_decrypt/main.c.

CreateDeviceKeyAlias()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateDeviceKeyAlias	(	const char *	device_key,
		const char *	device_key_alias
	)

Create a user friendly name/alias and associate it with a device key.

All subsequent function calls that require a device key may use the alias instead of the device key.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	device_key_alias	A character string containing the alias for the device key.

Returns

SUCCESS

DS_CANNOT_ASSIGN_EXISTING_ALIAS_NAME

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 device_key) == SUCCESS)
{
    if (CreateDeviceKeyAlias(device_key,"My_UDP_socket") != SUCCESS)
    {
        DeleteDevice("My_UDP_socket");
        return 1;
    }
} 

Examples

network_tcp/main.c, record_tcp/main.c, and record_udp/main.c.

CreateIPv4MulticastUDPSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateIPv4MulticastUDPSocketDevice	(	unsigned short	port,
		unsigned int	receive_queue_size,
		unsigned int	receive_buffer_size,
		boolean_type	disable_loopback_flag,
		unsigned int *	device_key_buffer_size_ptr,
		char *	device_key
	)

Creates a UDP socket to send and receive IP version 4 multicast packets at the specified port. UDP protocal does not guarantee delivery of the packet or packets being received in the order they were sent.

An optional receive queue may be created and associated with a UDP socket to minimizes the chances of the UDP socket dropping packets due to high packet rates or a bursty network. If the expected packet rate exceeds 100 packets per second, a receive queue may be required to avoid dropping packets. However, a receive queue does require additional memory allocations. A general rule is to size the queue to match the maximum number of packets per second.

The multicast socket must join a multicast group by calling JoinMulticastGroup prior to receiving packets sent to the IP multicast group address.

Parameters

[in]	port	The port number that is used to create the socket. Avoid most reserved port number by picking values greater than 6000 or if the port is just being used to send packets use 0 which lets the computer choose any available port number.
[in]	receive_queue_size	The maximum number of packets that can be received from the network and stored in the queue prior to dropping packets.
[in]	receive_buffer_size	The size of each individual buffer in the queue. Set to the maximum expected receive packet size in bytes.
[in]	disable_loopback_flag	Set this boolean_type variable to TRUE_OR_YES to prevent this socket from receiving multicast packets that it sends to a multicast group that it has joined. In addition, this variable will prevent this socket from receving multicast packets that are sent from other sockets that are using this socket's network interface card. The boolean_type is defined in the file "ds_shared.h" as follows: boolean_type Value FALSE_OR_NO 0 TRUE_OR_YES 1
[in,out]	device_key_buffer_size_ptr	The size of the buffer that will hold the device key character string. Set to MAX_DEVICE_KEY_SIZE of 100 bytes.
[out]	device_key	A character string that uniquely identifies each device.

Note

If the device_key buffer is not large enough to hold the new device key then DS_DEVICE_KEY_BUFFER_SIZE_ERROR is returned and device_key_buffer_size is updated with correct value for the device key buffer. The user may use the updated device_key_buffer_size value to preallocate the additional bytes in the device_key prior to calling CreateIPv4MulticastUDPSocketDevice a second time.

Returns

SUCCESS

DS_SOCKET_CREATION_ERROR

DS_SOCKET_BIND_ERROR

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_DEVICE_KEY_BUFFER_SIZE_ERROR

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
// Set disable_loopback_flag to false to allow host to receive multicast
// packets that are sent using the same network interface card. 
boolean_type disable_loopback_flag = FALSE_OR_NO; 
unsigned int key_buffer_size = 100;
char source_device_key[100];
if (CreateIPv4MulticastUDPSocketDevice(receive_port,
                                       receive_queue_size,
                                       receive_buffer_size,
                                       disable_loopback_flag,
                                       &key_buffer_size,
                                       receive_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_multicast/main.c.

CreateTCPClientSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateTCPClientSocketDevice	(	const char *	ip_address,
		unsigned short	port,
		unsigned int	receive_queue_size,
		unsigned int	receive_buffer_size,
		unsigned int *	device_key_buffer_size_ptr,
		char *	device_key
	)

Creates a TCP client socket. The client socket must make a separate connection request to a TCP listener sockets and connect to the listener's server socket. TCP protocal guarantees delivery of the packets in the order they were sent although it may break the packets up into segments that must be reassembled by the receiving application.

An optional receive queue may be created and associated with a TCP socket to improve performance due to high packet rates or a bursty network. If the expected packet rate exceeds 100 packets per second, a receive queue may help peformance. However, a receive queue does require additional memory allocations. A general rule is to size the queue to match the maximum number of packets per second.

A TCP client socket must send a connection request to a listener socket by calling ConnectSocketDevice prior to sending or receiving packets. In addition, if the TCP client socket is receiving packets the protocol may group or divide packets into segments which must be processed to retrieve individual packets.
If each packet has a predefined header with a packet size parameter, then the packets may be retrieved from the segments by defining the location of the packet size parameter using the DefinePHPPacketSizeField or by defining a packet sync pattern using DefinePHPSyncHexPattern function. A Packet Header Processor or PHP is associatied the with the TCP client socket using the AddPacketHeaderProcessor function. If the TCP client socket does not have an associated packet header processor, it can only provide packet segments and not complete packets to the user.

Parameters

[in]	ip_address	The IP addess used to create the socket.
[in]	port	The port number that is used to create the socket. Avoid most reserved port numbers by picking values greater than 6000 or use zero and let the computer choose an available port number.
[in]	receive_queue_size	The maximum number of packets that can be received from the network and stored in the queue prior to dropping packets.
[in]	receive_buffer_size	The size of each individual buffer in the queue. Set to the maximum expected receive packet size in bytes.
[in,out]	device_key_buffer_size_ptr	The size of the buffer that will hold the device key character string. Set to MAX_DEVICE_KEY_SIZE of 100 bytes.
[out]	device_key	A character string that uniquely identifies each device.

Note

If the device_key buffer is not large enough to hold the new device key then DS_DEVICE_KEY_BUFFER_SIZE_ERROR is returned and device_key_buffer_size is updated with correct value for the device key buffer. The user may use the updated device_key_buffer_size value to preallocate the additional bytes in the device_key prior to calling CreateTCPClientSocketDevice a second time.

Returns

SUCCESS

DS_SOCKET_CREATION_ERROR

DS_SOCKET_BIND_ERROR

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_DEVICE_KEY_BUFFER_SIZE_ERROR

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateTCPClientSocketDevice(ip_address,
                                source_port,
                                receive_queue_size,
                                receive_buffer_size,
                                &key_buffer_size,
                                source_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_tcp/main.c, and record_tcp/main.c.

CreateTCPListenerSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateTCPListenerSocketDevice	(	const char *	ip_address,
		unsigned short	port,
		unsigned int	receive_queue_size,
		unsigned int	receive_buffer_size,
		unsigned int *	device_key_buffer_size_ptr,
		char *	device_key
	)

Creates a TCP listener socket. The listener socket accepts and connects client sockets to newly created server sockets. TCP protocal guarantees delivery of the packets in the order they were sent although it may break the packets up into segments that must be reassembled by the receiving application.

An optional receive queue may be created and associated with a TCP socket to improve performance due to high packet rates or a bursty network. If the expected packet rate exceeds 100 packets per second, a receive queue may help peformance. However, a receive queue does require additional memory allocations. A general rule is to size the queue to match the maximum number of packets per second.

If the TCP server sockets created by the listener are receiving packets the protocol may group or divide packets into segments which must be processed to retrieve individual packets.
If each packet has a predefined header with a packet size parameter, then the packets may be retrieved from the segments by defining the location of the packet size parameter using the DefinePHPPacketSizeField function or by defining a packet sync pattern using DefinePHPSyncHexPattern function. A Packet Header Processor or PHP is associatied with the the TCP listener socket using the AddPacketHeaderProcessor function. If the TCP listener socket does not have an asscoiated packet header processor, it can only provide packet segments and not complete packets to the user.

Parameters

[in]	ip_address	The IP addess used to create the socket.
[in]	port	The port number that is used to create the socket. Avoid most reserved port number by picking values greater than 6000 or if the port is just being used to send packets use 0 which lets the computer choose any available port number.
[in]	receive_queue_size	The maximum number of packets that can be received from the network and stored in the queue prior to dropping packets.
[in]	receive_buffer_size	The size of each individual buffer in the queue. Set to the maximum expected receive packet size in bytes.
[in,out]	device_key_buffer_size_ptr	The size of the buffer that will hold the device key character string. Set to MAX_DEVICE_KEY_SIZE of 100 bytes.
[out]	device_key	A character string that uniquely identifies each device.

Note

If the device_key buffer is not large enough to hold the new device key then DS_DEVICE_KEY_BUFFER_SIZE_ERROR is returned and device_key_buffer_size is updated with correct value for the device key buffer. The user may use the updated device_key_buffer_size value to preallocate the additional bytes in the device_key prior to calling CreateTCPListenerSocketDevice a second time.

Returns

SUCCESS

DS_SOCKET_CREATION_ERROR

DS_SOCKET_BIND_ERROR

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_DEVICE_KEY_BUFFER_SIZE_ERROR

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 6300;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateTCPListenerSocketDevice(ip_address,
                                  source_port,
                                  receive_queue_size,
                                  receive_buffer_size,
                                  &key_buffer_size,
                                  source_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_tcp/main.c.

CreateUnicastUDPSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateUnicastUDPSocketDevice	(	const char *	ip_address,
		unsigned short	port,
		unsigned int	receive_queue_size,
		unsigned int	receive_buffer_size,
		unsigned int *	device_key_buffer_size_ptr,
		char *	device_key
	)

Creates a UDP socket to send and receive packets at the specified IP address and port. UDP protocal does not guarantee delivery of the packet or packets being received in the order they were sent.

An optional receive queue may be created and associated with a UDP socket to minimizes the chances of the UDP socket dropping packets due to high packet rates or a bursty network. If the expected packet rate exceeds 100 packets per second, a receive queue may be required to avoid dropping packets. However, a receive queue does require additional memory allocations. A general rule is to size the queue to match the maximum number of packets per second.

Parameters

[in]	ip_address	The IP addess used to create the socket.
[in]	port	The port number that is used to create the socket. Avoid most reserved port number by picking values greater than 6000 or if the port is just being used to send packets use 0 which lets the computer choose any available port number.
[in]	receive_queue_size	The maximum number of packets that can be received from the network and stored in the queue prior to dropping packets.
[in]	receive_buffer_size	The size of each individual buffer in the queue. Set to the maximum expected receive packet size in bytes.
[in,out]	device_key_buffer_size_ptr	The size of the buffer that will hold the device key character string. Set to MAX_DEVICE_KEY_SIZE of 100 bytes.
[out]	device_key	A character string that uniquely identifies each device.

Note

If the device_key buffer is not large enough to hold the new device key then DS_DEVICE_KEY_BUFFER_SIZE_ERROR is returned and device_key_buffer_size is updated with correct value for the device key buffer. The user may use the updated device_key_buffer_size value to preallocate the additional bytes in the device_key prior to calling CreateUnicastUDPSocketDevice a second time.

Returns

SUCCESS

DS_SOCKET_CREATION_ERROR

DS_SOCKET_BIND_ERROR

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_DEVICE_KEY_BUFFER_SIZE_ERROR

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
// A receive queue is not required since this socket is only sending 
// packets.
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 source_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_encrypt_decrypt/main.c, network_multicast/main.c, network_udp/main.c, network_udp_polling/main.c, and record_udp/main.c.

CreateUnixLocalClientSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION CreateUnixLocalClientSocketDevice	(	const char *	name,
		unsigned int	receive_queue_size,
		unsigned int	receive_buffer_size,
		unsigned int *	device_key_buffer_size_ptr,
		char *	device_key
	)

Creates a Unix local client socket for interprocess communication on a Linux operating system using a unique name and an abstract name space.

An optional receive queue may be created and associated with the socket.

Parameters

[in]	name	A unique name defining the communication endpoints.
[in]	receive_queue_size	The maximum number of packets that can be received from the server and stored in the queue prior to blocking.
[in]	receive_buffer_size	The size of each individual buffer in the queue. Set to the maximum expected receive packet size in bytes.
[in,out]	device_key_buffer_size_ptr	The size of the buffer that will hold the device key character string. Set to MAX_DEVICE_KEY_SIZE of 100 bytes.
[out]	device_key	A character string that uniquely identifies each device.

Note

If the device_key buffer is not large enough to hold the new device key then DS_DEVICE_KEY_BUFFER_SIZE_ERROR is returned and device_key_buffer_size is updated with correct value for the device key buffer. The user may use the updated device_key_buffer_size value to preallocate the additional bytes in the device_key prior to calling CreateUnixLocalClientSocketDevice a second time.

Returns

SUCCESS

DS_SOCKET_CREATION_ERROR

DS_SOCKET_BIND_ERROR

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_DEVICE_KEY_BUFFER_SIZE_ERROR

DS_NULL_POINTER_ERROR

Example:

char pathname[50];
// A receive queue is not required
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
strcpy(pathname,"./endpoint"); 
if (CreateUnixLocalClientSocketDevice(pathname,
                                      receive_queue_size,
                                      receive_buffer_size,
                                      &key_buffer_size,
                                      source_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

DefinePHPFixedPacketSize()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DefinePHPFixedPacketSize	(	const char *	php_name,
		unsigned int	fixed_packet_size
	)

Defines the size of all the packets that will be recieved by a device that is associated with this new or existing packet header processor.

If a TCP socket is receiving packets the protocol may group or divide packets into segments which must be processed to retrieve inidividual packets.
If each packet is a fixed size, then the packets may be retrieved from packet segments by associating the TCP socket with the packet header processor using the AddPacketHeaderProcessor function. If the socket does not have an asscoiated packet header processor, it can only provide packet segments and not complete packets to the user.

Parameters

[in]	php_name	A user friendly name for the packet header processor.
[in]	fixed_packet_size	The fixed size of the packet.

Returns

DS_NULL_POINTER_ERROR

Example:

char php_name[50];
unsigned int fixed_packet_size = 1200;
strcpy(php_name,"dr_php");
if (DefinePHPFixedPacketSize(php_name,
                             fixed_packet_size) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

DefinePHPPacketKeyField()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DefinePHPPacketKeyField	(	const char *	php_name,
		const char *	packet_key_name,
		unsigned int	byte_offset,
		unsigned int	bit_offset,
		unsigned int	length_in_bits,
		endian_byte_order	byte_order
	)

Defines the location of a packet key field in a new or existing packet header. All byte and bit offsets start at zero and are numbered from from left to right.

By defining the location of one or more packet keys in a packet header, it is possible to identify and record packet statistics for different packets
during packet reception by a device such as a socket. The socket device must be associated with the packet header processor using the AddPacketHeaderProcessor function and statistics recording must be turned on using the StartRecordingStatSnapshot function. The packet key string that is associated with the packet is a dotted numeric string of key field values.

Parameters

[in]	php_name	A user friendly name for the packet header processor.
[in]	packet_key_name	A name for the packet key field.
[in]	byte_offset	The byte offset to the start of the packet sequence count field starting at byte zero.
[in]	bit_offset	The bit offset to the start of the packet sequence count field starting at bit zero.
[in]	length_in_bits	The length of the packet sequence count field in bits. The length may not exceed 32 bits.
[in]	byte_order	Set the endian_byte_order variable to BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER to define multi-byte parameters in the packet header. The endian_byte_order is defined in the file "ds_shared.h" as follows: endian_byte_order Value BIG_ENDIAN_ORDER 0 LITTLE_ENDIAN_ORDER 1

Note

Packet headers usually use a big endian byte ordering scheme with the left most bit of each header parameter as the most significant bit and right most bit is the least significant with no byte swapping.

Returns

SUCCESS

DS_PHP_PACKET_KEY_FIELD_ERROR

DS_NULL_POINTER_ERROR

Example:

char php_name[50];
char key_name[50];
unsigned int byte_offset = 1;
unsigned int bit_offset = 4;
unsigned int length_in_bits  = 12;
endian_byte_order byte_order = BIG_ENDIAN_ORDER;
strcpy(php_name,"dr_php");
strcpy(key_name,"apid");
if (DefinePHPPacketKeyField(php_name,
                            key_name,
                            byte_offset,
                            bit_offset,
                            length_in_bits,
                            byte_order) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

DefinePHPPacketSequenceCountField()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DefinePHPPacketSequenceCountField	(	const char *	php_name,
		unsigned int	byte_offset,
		unsigned int	bit_offset,
		unsigned int	length_in_bits,
		endian_byte_order	byte_order
	)

Defines the location of a packet sequence count in a new or existing packet header. All byte and bit offsets start at zero and are numbered from from left to right.

By defining the location of a packet sequence count in a packet header, it is possible to detect and record the number of packet sequence errors that occur during packet reception by a device such as a socket. The socket device must be associated with the packet header processor using the AddPacketHeaderProcessor function and statistics recording must be turned on using the StartRecordingStatSnapshot function.

Parameters

[in]	php_name	A user friendly name for the packet header processor.
[in]	byte_offset	The byte offset to the start of the packet sequence count field starting at byte zero.
[in]	bit_offset	The bit offset to the start of the packet sequence count field starting at bit zero.
[in]	length_in_bits	The length of the packet sequence count field in bits. The length may not exceed 32 bits.
[in]	byte_order	Set the endian_byte_order variable to BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER to define multi-byte parameters in the packet header. The endian_byte_order is defined in the file "ds_shared.h" as follows: endian_byte_order Value BIG_ENDIAN_ORDER 0 LITTLE_ENDIAN_ORDER 1

Note

Packet headers usually use a big endian byte ordering scheme with the left most bit of each header parameter as the most significant bit and right most bit is the least significant with no byte swapping.

Returns

SUCCESS

DS_PHP_PACKET_SEQUENCE_COUNT_FIELD_ERROR

DS_NULL_POINTER_ERROR

Example:

char php_name[50];
unsigned int byte_offset = 1;
unsigned int bit_offset = 4;
unsigned int length_in_bits  = 20;
endian_byte_order byte_order = BIG_ENDIAN_ORDER;
strcpy(php_name,"dr_php");
if (DefinePHPPacketSequenceCountField(php_name,
                                      byte_offset,
                                      bit_offset,
                                      length_in_bits,
                                      byte_order) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

DefinePHPPacketSizeField()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DefinePHPPacketSizeField	(	const char *	php_name,
		unsigned int	byte_offset,
		unsigned int	bit_offset,
		unsigned int	length_in_bits,
		long	size_offset_value,
		endian_byte_order	byte_order
	)

Defines the location of a packet size field in a new or existing packet header. All byte and bit offsets start at zero and are numbered from from left to right.

If a TCP socket is receiving packets the protocol may group or divide packets into segments which must be processed to retrieve inidividual packets.
If each packet has a predefined header with a packet size parameter, then the packets may be retrieved from packet segments by defining the location of the packet size parameter or field. The TCP socket must then be associated with the packet header processor using the AddPacketHeaderProcessor function. If the socket does not have an associated packet header processor, it can only provide packet segments and not complete packets to the user.

Parameters

[in]	php_name	A user friendly name for the packet header processor.
[in]	byte_offset	The byte offset to the start of the packet size field starting at byte zero.
[in]	bit_offset	The bit offset to the start of the packet size field starting at bit zero.
[in]	length_in_bits	The length of the packet size field in bits. The length may not exceed 32 bits.
[in]	size_offset_value	A value added to the packet size to account for additional bytes that were not included in the packet size parameter.
[in]	byte_order	Set the endian_byte_order variable to BIG_ENDIAN_ORDER or LITTLE_ENDIAN_ORDER to define multi-byte parameters in the packet header. The endian_byte_order is defined in the file "ds_shared.h" as follows: endian_byte_order Value BIG_ENDIAN_ORDER 0 LITTLE_ENDIAN_ORDER 1

Note

Packet headers usually use a big endian byte ordering scheme with the left most bit of each header parameter as the most significant bit and right most bit is the least significant with no byte swapping.

Returns

SUCCESS

DS_PHP_PACKET_SIZE_FIELD_ERROR

DS_NULL_POINTER_ERROR

Example:

char php_name[50];
unsigned int byte_offset = 1;
unsigned int bit_offset = 4;
unsigned int length_in_bits  = 20;
long size_offset_value = 0;
endian_byte_order byte_order = BIG_ENDIAN_ORDER;
strcpy(php_name,"dr_php");
if (DefinePHPPacketSizeField(php_name,
                             byte_offset,
                             bit_offset,
                             length_in_bits,
                             size_offset_value,
                             byte_order) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_tcp/main.c.

DefinePHPSyncHexPattern()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DefinePHPSyncHexPattern	(	const char *	php_name,
		const char *	sync_hex_pattern,
		boolean_type	start_of_packet_sync_flag
	)

Defines a synch pattern for packets that require synchronization in a new or existing packet header processor. The sync pattern is described in hexadecimal format.

Valid hexadecimal input formats include upper or lower case (e.g., FFAA1122 or ffaa1122), may not exceed eight bytes and must be on a byte boundary. The sync pattern may be at the start or end of the packet. If a sync pattern is at the start of a packet and no packet size field is defined, the last packet received by the socket will not be processed since a sync pattern must be received to identify the end of a packet.

Parameters

[in]	php_name	A user friendly name for the packet header processor.
[in]	sync_hex_pattern	The hexadecimal representation of the sync pattern. Input formats may be upper or lower case (e.g., FFAA1122 or ffaa1122), may not exceed eight bytes and must be on a byte boundary.
[in]	start_of_packet_sync_flag	Set this boolean_type variable to TRUE_OR_YES if the sync pattern is at the start of the packet and not the end of the packet. The boolean_type is defined in the file "ds_shared.h" as follows: boolean_type Value FALSE_OR_NO 0 TRUE_OR_YES 1

Returns

SUCCESS

DS_PHP_SYNC_SIZE_ERROR

DS_PHP_SYNC_BYTE_BOUNDARY_ERROR

DS_NULL_POINTER_ERROR

Example:

char php_name[50];
char sync_hex_pattern[9];
boolean_type  start_of_packet_sync_flag = TRUE_OR_YES;
strcpy(php_name,"dr_php");
strcpy(sync_hex_pattern,"deadbeef");
if (DefinePHPSyncHexPattern(php_name,
                            sync_hex_pattern,
                            start_of_packet_sync_flag) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_tcp/main.c.

DeleteDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DeleteDevice

(

const char *

device_key

)

Decrements the device's use counter and if the device use counter is zero, all reference to the device are deleted and all device resources are released.

Parameters

[in]

device_key

A character string that uniquely identifies each device.

Returns

SUCCESS

DS_THREAD_STOP_ERROR

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
// A receive queue is not required since this socket is only sending 
// packets
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 source_device_key) != SUCCESS)
{
    DeleteDevice(source_device_key);
    return 1;
}

Examples

network_tcp/main.c.

DSCleanUp()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION DSCleanUp

(

)

Initiates a graceful shutdown of the Device Service library and all supporting device libraries, exits threads, and deallocates memory.

Note

This function should always be called when Device Services are no longer required or prior to exiting an application.

Returns

SUCCESS

DS_THREAD_STOP_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
// A receive queue is not required since this socket is only sending 
// packets.
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 source_device_key) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

cfdp_bp_destination/main.c, cfdp_bp_filestore_example/main.c, cfdp_bp_get_example/main.c, cfdp_bp_process_primitive_file/main.c, cfdp_bp_put_example/main.c, cfdp_destination/main.c, cfdp_filestore_example/main.c, cfdp_get_example_1/main.c, cfdp_get_example_2/main.c, cfdp_process_primitive_file/main.c, cfdp_put_example_1/main.c, cfdp_put_example_2/main.c, email_dropbox_example/main.c, email_example/main.c, email_file_dropbox_example/main.c, email_file_example/main.c, network_bp_destination/main.c, network_bp_destination_encrypt_decrypt/main.c, network_bp_polling/main.c, network_bp_source/main.c, network_bp_source_encrypt_decrypt/main.c, network_encrypt_decrypt/main.c, network_multicast/main.c, network_tcp/main.c, network_udp/main.c, network_udp_polling/main.c, record_api/main.c, record_tcp/main.c, record_udp/main.c, texting_dropbox_example/main.c, texting_example/main.c, and trek_cfdp_console.cpp.

FreeIPAddressStructArrayMemoryAlloc()

void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION FreeIPAddressStructArrayMemoryAlloc

(

ip_address_struct_type *

ip_address_struct_array_ptr

)

Frees the memory associated with the ip_address_struct_array_ptr that was returned by PopulateIPAddressStructArray.

Problems may develop when freeing the memory associated with the ip_address_struct_array_ptr if the DS library's compiler or run time environment does not match the application code's compiler or run time environment. This method is provided to avoid those problems by freeing the memory in the same library that allocated it.

Example:

unsigned int number_of_ip_address_structs;
ip_address_struct_type *ip_address_struct_array_ptr = NULL;
PopulateIPAddressStructArray(&number_of_ip_address_structs,
                             &ip_address_struct_array_ptr);
FreeIPAddressStructArrayMemoryAlloc(ip_address_struct_array_ptr);

Examples

network_multicast/main.c, network_tcp/main.c, network_udp/main.c, and network_udp_polling/main.c.

GeneratePublicPrivateKeyPair()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION GeneratePublicPrivateKeyPair	(	const char *	public_key_pathname,
		const char *	private_key_pathname
	)

Generates a public/private key pair based on Elliptic Curve Cryptography (ECC) using curve P-256.

The private key is wrapped/encrypted, prior to being stored in the private key file, using a default passphrase.

Parameters

[in]	public_key_pathname	The path and file name of the file that will be created to store the public key.
[in]	private_key_pathname	The path and file name of the file that will be created to store the private key.

Returns

SUCCESS

FAIL

Example:

char public_key_pathname[50];
char private_key_pathname[50];
 
strcpy(public_key_pathname,"/home/user/public.key");
strcpy(private_key_pathname,"/home/user/private.key");
 
if (GeneratePublicPrivateKeyPair(public_key_pathname,private_key_pathname) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_bp_destination_encrypt_decrypt/main.c, and network_encrypt_decrypt/main.c.

GeneratePublicPrivateKeyPairWithPassphrase()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION GeneratePublicPrivateKeyPairWithPassphrase	(	const char *	public_key_pathname,
		const char *	private_key_pathname,
		const char *	crypt_user_passphrase
	)

Generates a public/private key pair based on Elliptic Curve Cryptography (ECC) using curve P-256.

The private key is wrapped/encrypted, prior to being stored in the private key file, using a default passphrase or an optional user passphrase. If the user passphrase is an empty string, the private key will be wrapped using the default passphrase.

Parameters

[in]	public_key_pathname	The path and file name of the file that will be created to store the public key.
[in]	private_key_pathname	The path and file name of the file that will be created to store the private key.
[in]	crypt_user_passphrase	The passphrase that is used to wrap/encrypt the private key prior to storing the key in the private key file.

Returns

SUCCESS

FAIL

Example:

char public_key_pathname[50];
char private_key_pathname[50];
char user_passphrase[50];
 
strcpy(public_key_pathname,"/home/user/public.key");
strcpy(private_key_pathname,"/home/user/private.key")
strcpy(user_passphrase,"qwert12345!");
 
if (GeneratePublicPrivateKeyPair(public_key_pathname,private_key_pathname,user_passphrase) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_bp_destination_encrypt_decrypt/main.c, and network_encrypt_decrypt/main.c.

JoinMulticastGroup()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION JoinMulticastGroup	(	const char *	ip_address,
		const char *	multicast_group_address,
		const char *	device_key
	)

Associates a mulitcast socket with a multicast group address. A multicast socket must join a multicast group by calling JoinMulticastGroup prior to receiving packets sent to the IP multicast group address.

Parameters

[in]	ip_address	The default IP addess for packet transmission.
[in]	multicast_group_address	The multicast group address for receiving multicast packets. IPv4 Value Multicast address range 224.0.0.0 - 239.255.255.255 Global Scope 224.0.1.0 - 238.255.255.255 IPv6 Value Multicast address range ff prefix Reserved ff00::/16 - ff0f::/16 Multicast loopback address with x = 0-f ffx1::/16 Link Local (not routable) with x = 0-f ffx2::/16 Global Scope ffxe::/166 Reserved ffxf::/16
[in]	device_key	A character string that uniquely identifies each device.

Returns

SUCCESS

DS_SOCKET_JOIN_MULTICAST_GROUP_ERROR

DS_SOCKET_IP_ADDRESS_CONVERSION_ERROR

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
// Set disable_loopback_flag to false to allow host to receive multicast
// packets that are sent using the same network interface card.
boolean_type disable_loopback_flag = FALSE_OR_NO;  
unsigned int key_buffer_size = 100;
char receive_device_key[100];
char multi_ip_address[50];
if (CreateIPv4MulticastUDPSocketDevice(receive_port,
                                       receive_queue_size,
                                       receive_buffer_size,
                                       disable_loopback_flag,
                                       &key_buffer_size,
                                       receive_device_key) == SUCCESS)
{
    strcpy(ip_address,"127.0.0.1");  // IP addess for packet transmission
    // Multicast group IPV4 address range 224.0.0.0 - 239.255.255.255
    strcpy(multi_ip_address,"224.0.0.1"); 
    if (JoinMulticastGroup(ip_address,
                           multi_ip_address,
                           receive_device_key) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_multicast/main.c.

LogMessage()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION LogMessage	(	message_category	category,
		const char *	message
	)

Logs a user message in the log file. The maximum null terminated message size is 512 bytes.

Parameters

[in]	category	The pertinent enum message_category are defined in the file "trek_toolkit_common_api_ansi.h" as follows: message_category Value MSG_CAT_ERROR 16 MSG_CAT_WARNING 8 MSG_CAT_INFO 4 MSG_CAT_PROGRESS 2 MSG_CAT_DEBUG 1
[in]	message	The message to be logged.

Returns

SUCCESS

DS_WRITE_TO_LOG_FILE_ERROR

DS_NO_LOG_FILE_EXISTS

DS_NULL_POINTER_ERROR

Example:

char log_file_path[50];
char log_file_name[50];
strcpy(log_file_path,""); // Empty string so use the home directory 
                          // (e.g.,"C:/Users/<username>" or 
                          //  "/home/<username>")
strcpy(log_file_name,"logger.txt"); 
if (StartLoggingMessages(log_file_path,
                         log_file_name,
                         FALSE_OR_NO) == SUCCESS)
{
    LogMessage(MSG_CAT_INFO,"Test message.");
    // Log file name concatenated with the GMT time stamp 
    // (e.g., GMT_2015-01-01 01~01~01~001_logger.txt)
    StopLoggingMessages();  
    return 0;
}

Examples

cfdp_put_example_1/main.c, and network_multicast/main.c.

PopulateIPAddressStructArray()

void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION PopulateIPAddressStructArray	(	unsigned int *	number_of_ip_address_structs_ptr,
		ip_address_struct_type **	ip_address_struct_array_ptr
	)

Populates an array of ip_address_struct with the valid IP addresses of the host platform.

Note

The user is responsible for deallocating or freeing the memory associated with the ip_address_struct_array_ptr (i.e, free ip_address_struct_array_ptr). Problems may develop when freeing the memory associated with the ip_address_struct_array_ptr if the DS library's compiler or run time environment does not match the application code's compiler or run time environment.
The FreeIPAddressStructArrayMemoryAlloc function is provided to avoid those problems by freeing the memory in the same library that allocated it. If the host platform is supporting the Linux OS then IPv4 and IPv6 address and host name pairings must be present in the /etc/hosts file (e.g., 123.123.123.123 HostName).

Parameters

[out]	number_of_ip_address_structs_ptr	The number of ip_address_structs that are in the ip_address_struct_array.
[out]	ip_address_struct_array_ptr	An array of ip_address_structs. The ip_address_struct_type is defined in the file "ds_shared.h" as follows: char ip_address[50] ip_address_version_type ip_address_version ip_address_v6_category_type ip_address_v6_category The ip_address_version_type is defined in the file "ds_shared.h" as follows: ip_address_version_type Value IPV4 0 IPV6 1 The ip_address_v6_category_type is defined in the file "ds_shared.h" as follows: ip_address_v6_category_type Value UNDEFINED_IP_ADDRESS_V6_CATEGORY 0 GLOBAL_FIXED 1 GLOBAL_TEMPORARY 2 LINK_LOCAL 3 TAREDO_TUNNELING 4 IPV6_TO_IPV4_TUNNELING 5 MULTICAST 6 OTHER 7

Example:

unsigned int number_of_ip_address_structs;
ip_address_struct_type *ip_address_struct_array_ptr = NULL;
PopulateIPAddressStructArray(&number_of_ip_address_structs,
                             &ip_address_struct_array_ptr);
free(ip_address_struct_array_ptr);

Examples

network_multicast/main.c, network_tcp/main.c, network_udp/main.c, and network_udp_polling/main.c.

ReceivePacketFromDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION ReceivePacketFromDevice	(	const char *	device_key,
		unsigned int	receive_timeout,
		unsigned int *	packet_buffer_size_ptr,
		int *	packet_length_ptr,
		unsigned char *	packet_buffer_ptr,
		unsigned int *	message_code_ptr
	)

Receive a packet from a device within a specified time period.

If the packet buffer is not large enough to hold the received packet then DS_PACKET_BUFFER_SIZE_ERROR is returned, the packet_buffer_size is updated with correct value for the packet buffer and the packet is dropped.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	receive_timeout	The time, in milli seconds, to wait for a packet from a device.
[in]	packet_buffer_size_ptr	The size of the packet buffer.
[out]	packet_length_ptr	The length of the packet.
[out]	packet_buffer_ptr	The buffer containing the packet.
[out]	message_code_ptr	An unsigned integer value describing the packet and defined in ds_shared.h

Note

By default, telemetry's message code is DS_UNDEFINED.

Returns

SUCCESS

FAIL

DS_TIMEOUT

DS_PACKET_BUFFER_SIZE_ERROR

DS_THREAD_START_ERROR

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 10;
unsigned int receive_buffer_size = 50;
unsigned int key_buffer_size = 100;
char source_device_key[100];
unsigned int   receive_timeout;          // in milli seconds 
unsigned int   packet_buffer_size;
int            packet_length; 
unsigned char  packet_buffer[50]; 
unsigned int   message_code;
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 source_device_key) == SUCCESS)
{
    // Wait up to 2 seconds to receive the packet.
    receive_timeout = 2000;
    packet_buffer_size = 50;
    // Receive and print packet.
    if ( ReceivePacketFromSocketDevice( source_device_key,
                                        receive_timeout, 
                                        &packet_buffer_size,
                                        &packet_length,
                                        packet_buffer,
                                        &message_code) == SUCCESS)
    
    {
        printf("Data\t%s\n",(char *)packet_buffer);
    }
    return 0;
}

Examples

network_bp_polling/main.c.

ReceivePacketFromSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION ReceivePacketFromSocketDevice	(	const char *	device_key,
		unsigned int	receive_timeout,
		unsigned int *	packet_buffer_size_ptr,
		int *	packet_length_ptr,
		unsigned char *	packet_buffer_ptr,
		unsigned int *	message_code_ptr,
		unsigned int *	receive_from_ip_address_buffer_size_ptr,
		char *	received_from_ip_address,
		unsigned short *	received_from_port_ptr
	)

Receive a packet from a socket device within a specified time period.

If the packet buffer is not large enough to hold the received packet then DS_PACKET_BUFFER_SIZE_ERROR is returned, the packet_buffer_size is updated with correct value for the packet buffer and the packet is dropped.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	receive_timeout	The time, in milli seconds, to wait for a packet from a device.
[in]	packet_buffer_size_ptr	The size of the packet buffer.
[out]	packet_length_ptr	The length of the packet.
[in,out]	packet_buffer_ptr	The buffer containing the packet.
[out]	message_code_ptr	An unsigned integer value describing the packet and defined in ds_shared.h
[in,out]	receive_from_ip_address_buffer_size_ptr	The size of the received_from_ip_address buffer.
[out]	received_from_ip_address	The IP address of the socket that sent the packet.
[out]	received_from_port_ptr	The port number of the socket that sent the packet.

Note

The message code for telemetry packets received by a socket is DS_UNDEFINED.

Returns

SUCCESS

FAIL

DS_TIMEOUT

DS_PACKET_BUFFER_SIZE_ERROR

DS_THREAD_START_ERROR

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 10;
unsigned int receive_buffer_size = 50;
unsigned int key_buffer_size = 100;
char source_device_key[100];
unsigned int   receive_timeout;          // in milli seconds 
unsigned int   packet_buffer_size;
int            packet_length; 
unsigned char  packet_buffer[50]; 
unsigned int   message_code;
unsigned int   receive_from_ip_address_buffer_size;
char           received_from_ip_address[50]; 
unsigned short received_from_port;
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 source_device_key) == SUCCESS)
{
    // Wait up to 2 seconds to receive the packet.
    receive_timeout = 2000;
    packet_buffer_size = 50;
    receive_from_ip_address_buffer_size = 50;
    // Receive and print packet.
    if ( ReceivePacketFromSocketDevice( source_device_key,
                                        receive_timeout, 
                                        &packet_buffer_size,
                                        &packet_length,
                                        packet_buffer,
                                        &message_code,
                                        &receive_from_ip_address_buffer_size,
                                        received_from_ip_address,
                                        &received_from_port) == SUCCESS)
    
    {
        // Do something
    }
    return 0;
}

Examples

network_udp_polling/main.c.

RegisterAcceptConnection()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION RegisterAcceptConnection	(	const char *	listener_device_key,
		int(*)(const char *listener_device_key, const char *server_device_key, const char *connected_ip_address, unsigned short connected_port)	function_ptr
	)

Register a callback function to accept a connection request from a client socket.

Note

The registered callback function must return a value of SUCCESS or 0 for the connection to be accepted. A FAIL return value will drop the connection request. If the same callback function is registered with multiple devices the user is responsible for ensuring thread safe operation (i.e., a shared resource in the callback function should be wrapped in a mutex).

Parameters

[in]	listener_device_key	A character string that uniquely identifies a listener socket device.
[in]	function_ptr	A pointer to the callback function.

Callback function:

Parameters

[out]	listener_device_key	A character string that uniquely identifies the listener socket device that created server server that received the connection request.
[out]	server_device_key	A character string that uniquely identifies the server socket device that received the connection request.
[out]	connected_ip_address	The IP address of the client socket that is making the connection request.
[out]	connected_port	The port number of the client socket that is making the connection request.

Returns

SUCCESS

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

// ////////////////////////////////////////////////////////////////////////
//
// AcceptConnection provides ip_address and port information about the 
// client socket that is requesting a connection. Returning SUCCESS to 
// accept the connection request, return FAIL to reject the connection 
// request.
//
// ////////////////////////////////////////////////////////////////////////
 
int AcceptConnection  (const char     *listener_device_key,
                       const char     *server_device_key, 
                       const char     *connected_ip_address, 
                       unsigned short connected_port)
{
    printf("Info\tConnection request from IP address: %s and port: %d\n",
            connected_ip_address,
            connected_port);
    return(SUCCESS);
}
 
int main(int argc, char *argv[])
{
    char ip_address[50];
    unsigned short source_port = 6300;
    unsigned int receive_queue_size = 0;
    unsigned int receive_buffer_size = 0;
    unsigned int key_buffer_size = 100;
    char source_device_key[100];
    strcpy(ip_address,"127.0.0.1"); 
    if (CreateTCPListenerSocketDevice(ip_address,
                                      source_port,
                                      receive_queue_size,
                                      receive_buffer_size,
                                      &key_buffer_size,
                                      source_device_key) == SUCCESS)
    {
        If (RegisterAcceptConnection(source_device_key,
                                     &AcceptConnection) != SUCCESS)
        {
            DSCleanUp();
            return 1;
        }
    }
}

Examples

network_tcp/main.c.

RegisterDropConnectionFromClient()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION RegisterDropConnectionFromClient	(	const char *	client_device_key,
		void(*)(const char *disconnected_client_device_key, const char *disconnected_remote_ip_address, unsigned short disconnected_remote_port)	function_ptr
	)

Register a callback function to receive notification of a dropped connection when a client socket connection is dropped by its server.

Parameters

[in]	client_device_key	A character string that uniquely identifies the client socket device.
[in]	function_ptr	A pointer to the callback function.

Callback function:

Parameters

[out]	disconnected_client_device_key	A character string that uniquely identifies the client socket device that was disconnected.
[out]	disconnected_remote_ip_address	The IP address of the listener socket that accepted the connection.
[out]	disconnected_remote_port	The port number of the listener socket that accepted the connection.

Note

If the same callback function is registered with multiple devices the user is responsible for ensuring thread safe operation (i.e., a shared resource in the callback function should be wrapped in a mutex).

Returns

SUCCESS

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

// ////////////////////////////////////////////////////////////////////////
//
//  DropConnection provides ip_address and port information about the 
//  client socket that is dropping a connection.
//
// ////////////////////////////////////////////////////////////////////////
 
void DropConnection (const char     *disconnected_client_device_key, 
                     const char     *disconnected_remote_ip_address, 
                     unsigned short disconnected_remote_port)
{
    printf("Info\tConnection dropped from IP address: %s and port: %d\n",
            disconnected_remote_ip_address,
            disconnected_remote_port);
    return;
}
 
int main(int argc, char *argv[])
{
    char ip_address[50];
    unsigned short source_port = 6300;
    unsigned int receive_queue_size = 0;
    unsigned int receive_buffer_size = 0;
    unsigned int key_buffer_size = 100;
    char source_device_key[100];
    strcpy(ip_address,"127.0.0.1"); 
    if (CreateTCPClientSocketDevice(ip_address,
                                    source_port,
                                    receive_queue_size,
                                    receive_buffer_size,
                                    &key_buffer_size,
                                    source_device_key) == SUCCESS)
    {
        If (RegisterDropConnectionFromClient(source_device_key,
                                             &DropConnection) != SUCCESS)
        {
            DSCleanUp();
            return 1;
        }
    }
}

Examples

network_tcp/main.c.

RegisterDropConnectionFromListener()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION RegisterDropConnectionFromListener	(	const char *	listener_device_key,
		void(*)(const char *listener_device_key, const char *disconnected_server_device_key, const char *disconnected_remote_ip_address, unsigned short disconnected_remote_port)	function_ptr
	)

Register a callback function to receive notification of a dropped connection when a listener's server socket connection is dropped by its client.

Parameters

[in]	listener_device_key	A character string that uniquely identifies the listener socket device that created server socket.
[in]	function_ptr	A pointer to the callback function.

Callback function:

Parameters

[out]	listener_device_key	A character string that uniquely identifies the listener socket device that created the server socket that was disconnected.
[out]	disconnected_server_device_key	A character string that uniquely identifies the server socket device that was disconnected.
[out]	disconnected_remote_ip_address	The IP address of the client socket that dropped the connection.
[out]	disconnected_remote_port	The port number of the client socket that dropped the connection.

Note

If the same callback function is registered with multiple devices the user is responsible for ensuring thread safe operation (i.e., a shared resource in the callback function should be wrapped in a mutex).

Returns

SUCCESS

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

// ////////////////////////////////////////////////////////////////////////
//
//  DropConnection provides ip_address and port information about the 
//  client socket that is dropping a connection.
//
// ////////////////////////////////////////////////////////////////////////
 
void DropConnection   (const char     *listener_device_key,
                       const char     *disconnected_server_device_key, 
                       const char     *disconnected_remote_ip_address, 
                       unsigned short disconnected_remote_port)
{
    printf("Info\tConnection dropped from IP address: %s and port: %d\n",
            disconnected_remote_ip_address,
            disconnected_remote_port);
    return;
}
 
int main(int argc, char *argv[])
{
    char ip_address[50];
    unsigned short source_port = 6300;
    unsigned int receive_queue_size = 0;
    unsigned int receive_buffer_size = 0;
    unsigned int key_buffer_size = 100;
    char source_device_key[100];
    strcpy(ip_address,"127.0.0.1"); 
    if (CreateTCPListenerSocketDevice(ip_address,
                                      source_port,
                                      receive_queue_size,
                                      receive_buffer_size,
                                      &key_buffer_size,
                                      source_device_key) == SUCCESS)
    {
        If (RegisterDropConnectionFromListener(source_device_key,
                                               &DropConnection) != SUCCESS)
        {
            DSCleanUp();
            return 1;
        }
    }
}

RegisterMessage()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION RegisterMessage

(

void(*)(message_struct_type *message_struct_ptr)

function_ptr

)

Register a callback function to receive and process messages issued by the DS library.

Parameters

[in]

function_ptr

A pointer to the callback function.

Returns

DS_NULL_POINTER_ERROR

Callback function:

Parameters

[out]

message_struct_ptr

message structure defined in trek_toolkit_common_api_ansi_c.h as follows: Data Type Member Variable Name Description char time_stamp The GMT time the message was generated enum message_category category The message category (e.g., MSG_CAT_ERROR, MSG_CAT_ERROR_ALERT, MSG_CAT_WARNING, MSG_CAT_WARNING_ALERT, MSG_CAT_INFO, MSG_CAT_INFO_ALERT, MSG_CAT_PROGRESS, MSG_CAT_DEBUG) char message The message

Example:

void PrintMessage(message_struct_type *message_struct_ptr)
{
    if (message_struct_ptr->severity == MSG_CAT_ERROR)
    {
        printf("%s\n",message_struct_ptr->message);
    }
}
 
 
int main(int argc, char *argv[])
{
    RegisterMessage(&PrintMessage);
}

Examples

cfdp_bp_destination/main.c, cfdp_bp_filestore_example/main.c, cfdp_bp_get_example/main.c, cfdp_bp_process_primitive_file/main.c, cfdp_bp_put_example/main.c, cfdp_destination/main.c, cfdp_filestore_example/main.c, cfdp_get_example_1/main.c, cfdp_get_example_2/main.c, cfdp_process_primitive_file/main.c, cfdp_put_example_1/main.c, cfdp_put_example_2/main.c, email_dropbox_example/main.c, email_example/main.c, email_file_dropbox_example/main.c, email_file_example/main.c, network_bp_destination/main.c, network_bp_destination_encrypt_decrypt/main.c, network_bp_polling/main.c, network_bp_source/main.c, network_bp_source_encrypt_decrypt/main.c, network_encrypt_decrypt/main.c, network_multicast/main.c, network_tcp/main.c, network_udp/main.c, network_udp_polling/main.c, record_api/main.c, record_tcp/main.c, record_udp/main.c, texting_dropbox_example/main.c, texting_example/main.c, and trek_cfdp_console.cpp.

RegisterReceivePacket()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION RegisterReceivePacket	(	const char *	device_key,
		void(*)(const char *key, int packet_length, unsigned char *packet_buffer_ptr)	function_ptr
	)

Register a callback function to receive packets from a device.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	function_ptr	A pointer to the callback function.

Callback function:

Parameters

[out]	key	A character string that is defined by the device that is receiving packets (for BP devices the key string is formatted as follows: <source node number>.<source service number> (e.g., 1.64)
[out]	packet_length	The length of the packet.
[out]	packet_buffer_ptr	The buffer containing the packet.

Note

If the same callback function is registered with multiple devices the user is responsible for ensuring thread safe operation (i.e., a shared resource in the callback function should be wrapped in a mutex).

Returns

SUCCESS

DS_THREAD_START_ERROR

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

void ReceivePacket (const char     *key,
                    int            packet_length,
                    unsigned char  *packet_buffer_ptr)
{
    // Do something
}
 
 
int main(int argc, char *argv[])
{
    char device_key[100];
 
    // Create a device with and return a device key
 
    // Recieve packets from the device
    RegisterReceivePacket(device_key,&ReceivePacket);
}

Examples

network_bp_destination/main.c, network_bp_destination_encrypt_decrypt/main.c, network_bp_source/main.c, and network_bp_source_encrypt_decrypt/main.c.

RegisterReceivePacketFromSocket()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION RegisterReceivePacketFromSocket	(	const char *	device_key,
		void(*)(const char *device_key, int packet_length, unsigned char *packet_buffer_ptr, const char *received_from_ip_address, unsigned short received_from_port)	function_ptr
	)

Register a callback function to receive packets from a socket device.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	function_ptr	A pointer to the callback function.

Callback function:

Parameters

[out]	device_key	A character string that uniquely identifies each device.
[out]	packet_length	The length of the packet.
[out]	packet_buffer_ptr	The buffer containing the packet.
[out]	received_from_ip_address	The IP address of the socket that sent the packet.
[out]	recieved_from_port	The port number of the socket that sent the packet.

Note

If the same callback function is registered with multiple devices the user is responsible for ensuring thread safe operation (i.e., a shared resource in the callback function should be wrapped in a mutex).

Returns

SUCCESS

DS_THREAD_START_ERROR

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

void ReceivePacket (const char     *device_key,
                    int            packet_length,
                    unsigned char  *packet_buffer_ptr,
                    const char     *received_from_ip_address,
                    unsigned short recieved_from_port)
{
    // Do something
}
 
 
int main(int argc, char *argv[])
{
            char ip_address[50];
        char source_device_key[100];
    unsigned int key_buffer_size = 100;
        strcpy(ip_address,"127.0.0.1");  // Use loopback address
        if (CreateUnicastUDPSocketDevice(ip_address,
                                 6100,
                                 0,
                                 0,
                                 &key_buffer_size,
                                 source_device_key) == SUCCESS)
            {
                RegisterReceivePacket(source_device_key,&ReceivePacket);
            }
}   

Examples

network_encrypt_decrypt/main.c, network_multicast/main.c, network_tcp/main.c, and network_udp/main.c.

ResetStatistics()

void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION ResetStatistics

(

)

Resets or zero's the device and packet statistics.

Example:

char record_file_path[50];
char record_file_name[50];
strcpy(record_file_path,""); // Empty string so use the home directory 
                             // (e.g.,"C:/Users/<username>" or 
                             //  "/home/<username>")
strcpy(record_file_name,"statistics.csv");
// Record only device statistics
if (StartRecordingStatSnapshot(record_file_path,
                               record_file_name,
                               FALSE_OR_NO) == SUCCESS)
{
    ResetStatistics(); 
 
    return 0;
}

SendPacket()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION SendPacket	(	const char *	device_key,
		int	packet_length,
		unsigned char *	packet_buffer_ptr
	)

Sends a packet to a device.

If the device is a TCP client socket, a packet is sent to the connected server socket. If the device is a TCP listener socket a packet is sent from all the TCP listener socket's server sockets to the each server's connected client socket.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	packet_length	The length of the packet.
[in]	packet_buffer_ptr	A buffer containing the packet.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short listener_port = 6300;
unsigned short client_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int connection_timeout_msec = 2000;
unsigned int key_buffer_size = 100;
char listener_device_key[100];
char client_device_key[100];
unsigned char packer_buffer[100];
strcpy(ip_address,"127.0.0.1"); // Use loopback address
memset(packer_buffer,0x00,50);  // Create a 50 byte packet
if (CreateTCPListenerSocketDevice(ip_address,
                                  listener_port,
                                  receive_queue_size,
                                  receive_buffer_size,
                                  &key_buffer_size,
                                  listener_device_key) == SUCCESS)
{
    if (CreateTCPClientSocketDevice(ip_address,
                                    client_port,
                                    receive_queue_size,
                                    receive_buffer_size,
                                    &key_buffer_size,
                                    client_device_key) == SUCCESS)
    {
        if (ConnectSocketDevice(client_device_key,
                                ip_address,
                                listener_port,
                                connection_timeout_msec) == SUCCESS)
        {
            if (SendPacket(client_device_key,50,packer_buffer) != SUCCESS)
            {
                DSCleanUp();
                return 1;
            }
        }
    }
}

Examples

network_tcp/main.c, and record_tcp/main.c.

SendPacketFromBPDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION SendPacketFromBPDevice	(	const char *	device_key,
		int	packet_length,
		unsigned char *	packet_buffer_ptr,
		long long	destination_node_number,
		unsigned int	destination_service_number
	)

Sends a packet from a bundle protocol device to the destination node.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	packet_length	The length of the packet.
[in]	packet_buffer_ptr	A buffer containing the packet.
[in]	destination_node_number	The node number that will receive the bundle.
[in]	destination_service_number	The unsigned integer value service number that associates the destination device with ION's configured BP service.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

long long destination_node_number,
unsigned int destination_service_number
unsigned int source_service_number;
unsigned int lifespan;
bp_class_of_service_type cos;                   
unsigned int ordinal;           
bp_transmission_mode_type mode;             
bp_criticality_type criticality;
unsigned int key_buffer_size = 100;
char source_device_key[100];
unsigned char packet_buffer[1400];
 
destination_node_number = 321;
destination_service_number = 4;
source_service_number = 3;
lifespan = 86400;
cos = BPD_STD_PRIORITY;             
ordinal = 0;                
mode = BPD_ASSURED;
criticality = BPD_NOT_CRITICAL;
 
if (CreateBPDevice( source_service_number,
                    lifespan,
                    cos,
                    ordinal,
                    mode,
                    criticality,
                    &key_buffer_size,
                    source_device_key) != SUCCESS)
{
    if (SendPacketFromBPDevice(source_device_key,
                               50,
                               packer_buffer,
                               destination_node_number,
                               destination_service_number) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_bp_destination/main.c, network_bp_destination_encrypt_decrypt/main.c, network_bp_polling/main.c, network_bp_source/main.c, and network_bp_source_encrypt_decrypt/main.c.

SendPacketFromTCPServerSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION SendPacketFromTCPServerSocketDevice	(	const char *	listener_device_key,
		const char *	server_device_key,
		int	packet_length,
		unsigned char *	packet_buffer_ptr
	)

Sends a packet from a TCP server socket device to the connected client socket device.

Parameters

[in]	listener_device_key	A character string that identifies listener socket device.
[in]	server_device_key	A character string that identifies server socket device. Set to "" to send packet from all server devices currently associated with the listener device.
[in]	packet_length	The length of the packet.
[in]	packet_buffer_ptr	A buffer containing the packet.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short listener_port = 6300;
unsigned short client_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int connection_timeout_msec = 2000;
unsigned int key_buffer_size = 100;
char listener_device_key[100];
char client_device_key[100];
unsigned char packer_buffer[100];
strcpy(ip_address,"127.0.0.1"); // Use loopback address
memset(packer_buffer,0x00,50);  // Create a 50 byte packet
if (CreateTCPListenerSocketDevice(ip_address,
                                  listener_port,
                                  receive_queue_size,
                                  receive_buffer_size,
                                  &key_buffer_size,
                                  listener_device_key) == SUCCESS)
{
    if (CreateTCPClientSocketDevice(ip_address,
                                    client_port,
                                    receive_queue_size,
                                    receive_buffer_size,
                                    &key_buffer_size,
                                    client_device_key) == SUCCESS)
    {
        if (ConnectSocketDevice(client_device_key,
                                ip_address,
                                listener_port,
                                connection_timeout_msec) == SUCCESS)
        {
 
            // Acquire server device key from the RegisterAcceptConnection callback function
 
            if (SendPacketFromTCPServerSocketDevice(listener_device_key,
                                                    server_device_key,
                                                    100,
                                                    packer_buffer) != SUCCESS)
            {
                DSCleanUp();
                return 1;
            }
        }
    }
}

SendPacketFromUDPSocketDevice()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION SendPacketFromUDPSocketDevice	(	const char *	device_key,
		int	packet_length,
		unsigned char *	packet_buffer_ptr,
		const char *	send_to_ip_address,
		unsigned short	send_to_port
	)

Sends a packet from UDP socket device to the IP address and port number of a corresponding UDP socket device.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	packet_length	The length of the packet.
[in]	packet_buffer_ptr	A buffer containing the packet.
[in]	send_to_ip_address	The IP address of the UDP socket that will receive the packet.
[in]	send_to_port	The port number of the UDP socket that will receive the packet.

Returns

SUCCESS

FAIL

DS_DEVICE_NOT_FOUND

DS_SOCKET_IP_ADDRESS_CONVERSION_ERROR

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
char send_to_ip_address[50];
unsigned short source_port = 0;
 unsigned short send_to_port = 6100;
// A receive queue is not required since this socket is only sending 
// packets.
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
char source_device_key[100];
unsigned char packer_buffer[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
strcpy(send_to_ip_address,"127.0.0.1");  
memset(packer_buffer,0x00,50);  // Create a 50 byte packet
if (CreateUnicastUDPSocketDevice(ip_address,
                                 source_port,
                                 receive_queue_size,
                                 receive_buffer_size,
                                 &key_buffer_size,
                                 source_device_key) == SUCCESS)
{
    if (SendPacketFromUDPSocket(source_device_key,
                                50,
                                packer_buffer,
                                send_to_ip_address,
                                send_to_port) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_encrypt_decrypt/main.c, network_multicast/main.c, network_udp/main.c, network_udp_polling/main.c, and record_udp/main.c.

SetMulticastTTL()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION SetMulticastTTL	(	const char *	device_key,
		unsigned short	multicast_ttl
	)

Sets the time to live for a socket that is sending packets to a multicast address.

Multicast time-to-live indicates the scope or range in which a packet may be forwarded. The default value is one.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	multicast_ttl	Time to live for multicast packet. Range Value Restricted to the same host 0 Restricted to the same subnet 1 Restricted to the same site 2-32 Restricted to the same region 33-64 Restricted to the same continent 65-128 Unrestricted 129-255

Returns

SUCCESS

DS_DEVICE_NOT_FOUND

DS_SOCKET_OPTION_MULTICAST_TTL_ERROR

DS_NULL_POINTER_ERROR

Example:

unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
// Set disable_loopback_flag to false to allow host to receive multicast
// packets that are sent using the same network interface card.
boolean_type disable_loopback_flag = FALSE_OR_NO;  
unsigned int key_buffer_size = 100;
unsigned short multicast_ttl =1;
char receive_device_key[100];
if (CreateIPv4MulticastUDPSocketDevice(receive_port,
                                       receive_queue_size,
                                       receive_buffer_size,
                                       disable_loopback_flag,
                                       &key_buffer_size,
                                       receive_device_key) == SUCCESS)
{
    if (SetMulticastTTL(receive_device_key,multicast_ttl) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_multicast/main.c.

SetTCPKeepalive()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION SetTCPKeepalive	(	const char *	device_key,
		unsigned long	keepalive_time,
		unsigned long	keepalive_interval,
		unsigned long	keepalive_probes
	)

Sets the TCP keepalive parameters to determine whether the TCP connection is still up and running or has broken.

Parameters

[in]	device_key	A character string that uniquely identifies each device.
[in]	keepalive_time	The timeout, in seconds, with no activity until the first keepalive packet is sent.
[in]	keepalive_interval	The interval, in seconds, when successive keep-alive packets are sent if no acknowledgement is received.
[in]	keepalive_probes	The number of consecutive probes/packets that are sent without an acknowledgement prior to declaring the connection broken.

Note

On the Windows operating system, the number of keepalive probes is set to 10 and cannot be changed.

Returns

SUCCESS

DS_SOCKET_OPTION_KEEPALIVE_ERROR

DS_DEVICE_NOT_FOUND

DS_NULL_POINTER_ERROR

Example:

char ip_address[50];
unsigned short source_port = 0;
unsigned int receive_queue_size = 0;
unsigned int receive_buffer_size = 0;
unsigned int key_buffer_size = 100;
unsigned long keepalive_time= 3600;
unsigned long keepalive_interval = 300;
unsigned long keepalive_probes = 10;
char source_device_key[100];
strcpy(ip_address,"127.0.0.1");  // Use loopback address
if (CreateTCPClientSocketDevice(ip_address,
                                source_port,
                                receive_queue_size,
                                receive_buffer_size,
                                &key_buffer_size,
                                source_device_key) == SUCCESS)
{
    if (SetTCPKeepalive(source_device_key,
                        keepalive_time,
                        keepalive_interval,
                        keepalive_probes) != SUCCESS)
    {
        DSCleanUp();
        return 1;
    }
}

Examples

network_tcp/main.c.

StartLoggingMessages()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION StartLoggingMessages	(	const char *	log_file_path,
		const char *	log_filename,
		boolean_type	log_debug_messages
	)

Starts logging messages to a file.

Parameters

[in]	log_file_path	The path of the log file. If an empty string is provided, the default path is the user's home directory.
[in]	log_filename	The base file name of the log file. When logging is stopped, this name will be concatenated with a GMT time string.
[in]	log_debug_messages	Set this boolean_type variable to TRUE_OR_YES to log debug messages. The boolean_type is defined in the file "ds_shared.h" as follows: boolean_type Value FALSE_OR_NO 0 TRUE_OR_YES 1

Returns

SUCCESS

DS_FILE_OPEN_ERROR

DS_NULL_POINTER_ERROR

DS_RECORDING_CURRENTLY_ACTIVATED

Example:

char log_file_path[50];
char log_filename[50];
strcpy(log_file_path,""); // Empty string so use the home directory 
                          // (e.g.,"C:/Users/<username>" or 
                          //  "/home/<username>")
strcpy(log_filename,"logger");
// Log only error, warning, info and progress messages
if (StartLoggingMessages(log_file_path,
                         log_filename,
                         FALSE_OR_NO) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

network_bp_destination/main.c, network_bp_polling/main.c, network_bp_source/main.c, network_encrypt_decrypt/main.c, network_multicast/main.c, network_tcp/main.c, network_udp/main.c, and network_udp_polling/main.c.

StartRecordingStatSnapshot()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION StartRecordingStatSnapshot	(	const char *	record_file_path,
		const char *	record_filename,
		boolean_type	record_packet_statistics_flag
	)

Starts recording a snapshot of the current statistics to a file.

The snapshot is updated once a second with the latest statistics. Previous statistic snapshots are overwritten.

Parameters

[in]	record_file_path	The path of the record file. If an empty string is provided, the default path is the user's home directory.
[in]	record_filename	The base filename of the log file. When recording is stopped, this name will be concatenated with a GMT time string.
[in]	record_packet_statistics_flag	Set this boolean_type variable to TRUE_OR_YES to log both device and packet statistics messages. The boolean_type is defined in the file "ds_shared.h" as follows: boolean_type Value FALSE_OR_NO 0 TRUE_OR_YES 1

Note

A packet header processor should be associated with a device if packets statistics are required.

Returns

SUCCESS

DS_THREAD_START_ERROR

DS_THREAD_TIMEOUT

DS_NULL_POINTER_ERROR

DS_RECORDING_CURRENTLY_ACTIVATED

Example:

char record_file_path[50];
char record_filename[50];
strcpy(record_file_path,""); // Empty string so use the home directory 
                             // (e.g.,"C:/Users/<username>" or 
                             //  "/home/<username>")
strcpy(record_filename,"statistics.csv");
// Record only device statistics
if (StartRecordingStatSnapshot(record_file_path,
                               record_filename,
                               FALSE_OR_NO) != SUCCESS)
{
    DSCleanUp();
    return 1;
}

Examples

cfdp_put_example_1/main.c, and network_tcp/main.c.

StopLoggingMessages()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION StopLoggingMessages

(

)

Stops logging messages to a file, closes the log file and renames the log file by concatenating the log file name with a GMT time string.

Returns

SUCCESS

DS_ERROR_RENAMING_LOG_FILE

DS_FILE_CLOSE_ERROR

Example:

char log_file_path[50];
char log_file_name[50];
strcpy(log_file_path,""); // Empty string so use the home directory 
                          // (e.g.,"C:/Users/<username>" or 
                          //  "/home/<username>")
strcpy(log_file_name,"logger.txt"); 
if (StartLoggingMessages(log_file_path,
                         log_file_name,
                         FALSE_OR_NO) == SUCCESS)
{
    // Log file name concatenated with the GMT time stamp 
    // (e.g., GMT_2015-01-01_01~01~01~001_logger.txt)
    StopLoggingMessages();  
    return 0;
}

Examples

network_bp_destination/main.c, network_bp_polling/main.c, network_bp_source/main.c, network_encrypt_decrypt/main.c, network_multicast/main.c, network_tcp/main.c, network_udp/main.c, record_api/main.c, record_tcp/main.c, and record_udp/main.c.

StopLoggingMessagesEx()

int EXPORT_THIS_TOOLKIT_DS_C_FUNCTION StopLoggingMessagesEx

(

char *

time_tagged_log_file_name

)

Stops logging messages to a file, closes the log file and renames the log file by concatenating the log file name with a GMT time string and returns the new file name.

Returns

SUCCESS

DS_ERROR_RENAMING_LOG_FILE

DS_FILE_CLOSE_ERROR

Example:

char log_file_path[50];
char log_file_name[50];
char time_tagged_log_file_name[50];
strcpy(log_file_path,""); // Empty string so use the home directory
// (e.g.,"C:/Users/<username>" or
//  "/home/<username>")
strcpy(log_file_name,"logger.txt");
if (StartLoggingMessages(log_file_path,
log_file_name,
FALSE_OR_NO) == SUCCESS)
{
// Log file name concatenated with the GMT time stamp
// (e.g., GMT_2015-01-01_01~01~01~001_logger.txt)
StopLoggingMessagesEx(time_tagged_log_file_name);
return 0;
}

StopRecordingStatSnapshot()

void EXPORT_THIS_TOOLKIT_DS_C_FUNCTION StopRecordingStatSnapshot

(

)

Stops recording statisitics to a file, closes the record file and renames the record file by concatenating the record file name with a GMT time string.

Example:

char record_file_path[50];
char record_file_name[50];
strcpy(record_file_path,""); // Empty string so use the home directory 
                             // (e.g.,"C:/Users/<username>" or 
                             //  "/home/<username>")
strcpy(record_file_name,"statistics.csv");
// Record only device statistics
if (StartRecordingStatSnapshot(record_file_path,
                               record_file_name,
                               FALSE_OR_NO) == SUCCESS)
{
    // Record file name concatenated with the GMT time stamp 
    // (e.g., GMT_2015-01-01 01~01~01~001_statistics.csv)
    StopRecordingStatisitics();  
    return 0;
}

Examples

network_tcp/main.c.