Methods that every Transport-Plugin implementation must provide. More...

Data Structures
struct	NDDS_Transport_PluginImpl
	Base "class" for a Transport Plugin implementation. More...

Typedefs
typedef struct NDDS_Transport_PluginImpl	NDDS_Transport_Plugin
	"Pure virtual class" for all transports => All transport implementations must implement ALL methods, even if they are a dummy method.

typedef RTI_INT32(*	NDDS_Transport_Send_Fcn )(NDDS_Transport_Plugin self, const NDDS_Transport_SendResource_t sendresource_in, const NDDS_Transport_Address_t dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in, const NDDS_Transport_Buffer_t buffer_in[], RTI_INT32 buffer_count_in, void reserved)
	Synchronous gather send. Send multiple buffers by means of a previously created SendResource to a pre-registered destination.

typedef RTI_INT32(*	NDDS_Transport_Recv_Fcn_rEA )(NDDS_Transport_Plugin self, NDDS_Transport_Message_t message_out, const NDDS_Transport_Buffer_t buffer_in, const NDDS_Transport_RecvResource_t recvresource_in, void *reserved)
	Blocking-receive call to retrieve messages received by a Transport Plugin.

typedef void(*	NDDS_Transport_Return_Loaned_Buffer_Fcn_rEA )(NDDS_Transport_Plugin self, const NDDS_Transport_RecvResource_t recvresource_in, NDDS_Transport_Message_t message_in, void reserved)
	Method used by NDDS to return a buffer loaned by a Transport Plugin in the `receive_rEA()` call to pass a received message to NDDS.

typedef RTI_INT32(*	NDDS_Transport_Unblock_Recv_Fcn_rrEA )(NDDS_Transport_Plugin self, const NDDS_Transport_RecvResource_t recvresource_in, void *reserved)
	Called by NDDS to unblock a thread blocked on `receive_rEA()` or otherwise return immediately when `receive_rEA()` is called.

typedef RTI_INT32(*	NDDS_Transport_Create_RecvResource_Fcn_rrEA )(NDDS_Transport_Plugin self, NDDS_Transport_RecvResource_t recvresource_out, NDDS_Transport_Port_t recv_port_inout, const NDDS_Transport_Address_t multicast_address_in, RTI_INT32 reserved)
	Called by NDDS to initialize the Transport Plugin to receive messages for a given port and/or multicast address. A handle to the transport-specific data structure (RecvResource) used by NDDS to collect received messages from this plugin is returned.

typedef void(*	NDDS_Transport_Destroy_RecvResource_Fcn_rrEA )(NDDS_Transport_Plugin self, const NDDS_Transport_RecvResource_t recvresource_in)
	Called to destroy a RecvResource previously created with NDDS_Transport_Create_RecvResource_Fcn_rrEA.

typedef RTI_INT32(*	NDDS_Transport_Share_RecvResource_Fcn_rrEA )(NDDS_Transport_Plugin self, const NDDS_Transport_RecvResource_t recvresource_in, const NDDS_Transport_Port_t recv_port_in, const NDDS_Transport_Address_t *multicast_address_in, RTI_INT32 reserved)
	Called to see if an existing RecvResource can be shared to receive messages on a different port/multicast address.

typedef RTI_INT32(*	NDDS_Transport_Unshare_RecvResource_Fcn_rrEA )(NDDS_Transport_Plugin self, const NDDS_Transport_RecvResource_t recvresource_in, const NDDS_Transport_Port_t recv_port_in, const NDDS_Transport_Address_t *multicast_address_in, RTI_INT32 reserved)
	Called to unshare a RecvResource that was previously successfully shared for a port/address.

typedef RTI_INT32(*	NDDS_Transport_Create_SendResource_Fcn_srEA )(NDDS_Transport_Plugin self, NDDS_Transport_SendResource_t sendresource_out, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in)
	Called by NDDS to initialize the Transport Plugin to send messages to the destination as defined by the passed in address/port. A handle to the transport-specific data structure (SendResource) used by NDDS to send messages with this plugin is returned.

typedef void(*	NDDS_Transport_Destroy_SendResource_Fcn_srEA )(NDDS_Transport_Plugin self, const NDDS_Transport_SendResource_t sendresource_in)
	Called to destroy a SendResource previously created with NDDS_Transport_Create_SendResource_Fcn_srEA.

typedef RTI_INT32(*	NDDS_Transport_Share_SendResource_Fcn_srEA )(NDDS_Transport_Plugin self, const NDDS_Transport_SendResource_t sendresource_in, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in)
	Called to see if an existing SendResource can be shared to send messages to a different destination (address/port).

typedef const char (	NDDS_Transport_Get_Class_Name_Fcn_cEA )(NDDS_Transport_Plugin *self)
	Returns the string class name of the transport.

typedef RTI_INT32(*	NDDS_Transport_Unshare_SendResource_Fcn_srEA )(NDDS_Transport_Plugin self, const NDDS_Transport_SendResource_t sendresource_in, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in)
	Called to unshare a SendResource that was previously successfully shared for an address/port.

typedef RTI_INT32(*	NDDS_Transport_String_To_Address_Fcn_cEA )(NDDS_Transport_Plugin self, NDDS_Transport_Address_t address_out, const char *address_in)
	Called to convert a Transport-Plugin-specific string representation of an address to an IPv6 address representation.

typedef RTI_INT32(*	NDDS_Transport_Get_Receive_Interfaces_Fcn_cEA )(NDDS_Transport_Plugin self, RTI_INT32 found_more_than_provided_for_out, RTI_INT32 *interface_reported_count_out, NDDS_Transport_Interface_t interface_array_inout[], RTI_INT32 interface_array_size_in)
	Called to retrieve a list of interfaces that can be used to receive messages through this Transport Plugin.

typedef RTI_INT32(*	NDDS_Transport_Register_Listener_Fcn_cEA )(NDDS_Transport_Plugin self, NDDS_Transport_Listener listener_in)
	Called by NDDS to register a set of callback functions that should be called by the Transport Plugin instance when it detects specific dynamic changes in its state.

typedef void(*	NDDS_Transport_Delete_Fcn_cEA )(NDDS_Transport_Plugin self, void reserved)
	Method used to delete an instance of a Transport Plugin.

Detailed Description

Methods that every Transport-Plugin implementation must provide.

Typedef Documentation

typedef struct NDDS_Transport_PluginImpl NDDS_Transport_Plugin

"Pure virtual class" for all transports => All transport implementations must implement ALL methods, even if they are a dummy method.

NDDS_Transport_Plugin is a structure used by NDDS to interact with an instance of a Transport Plugin. In a C++ implementation, this would be a base class. However since the NDDS Transport API is written in C, this structure will serve as the base class.

All implementations of a Transport Plugin must allocate this structure and fill in the structure members, properties and functions, when an instance of the Transport Plugin is created. The instance of the plugin is registered with NDDS using a pointer to the structure, see .

An implementation of a Transport Plugin may create a "derived class" of NDDS_Transport_Plugin by defining a structure that contains NDDS_Transport_Plugin as the first member of the structure.

For example

struct MyTransport_Plugin {
    NDDS_Transport_Plugin parent;
    RTI_INT32 myTransportSpecificParam1;
    RTI_INT32 myTransportSpecificParam2;
    float myTransportSpecificParam3;
    < other transport specific data/structures/pointers >
};
NDDS_Transport_Plugin *MyTransport_Plugin_new() {
    MyTransport_Plugin *me = malloc(sizeof(MyTransport_Plugin));
    < initialization of me >
    me->parent.<methods> = <MyTransport_Plugin_methods>;
    ...
    return (NDDS_Transport_Plugin *) me;
}

In this way, even though the structure returned by the Transport Plugin creation routine is really of type MyTransport_Plugin, it can be manipulated by the NDDS core as if it was of type NDDS_Transport_Plugin.

Then, in the MyTransport_Plugin implementations of the Transport Plugin API, the NDDS_Transport_Plugin pointer passed in can be casted back to MyTransport_Plugin.

For example,

 RTI_INT32 MyTransport_Plugin_send(
 NDDS_Transport_Plugin               *self,
     const NDDS_Transport_SendResource_t *sendresource_in,
     const NDDS_Transport_Address_t      *dest_address_in, 
     const NDDS_Transport_Port_t          dest_port_in,
 RTI_INT32                            transport_priority_in,          
     const NDDS_Transport_Buffer_t        buffer_in[], 
     RTI_INT32                            buffer_count_in,
     void                                *reserved )
{
     MyTransport_Plugin *me = (MyTransport_Plugin *)self;
     < now the code can access transport-specific storage through me >
     ...
}

typedef RTI_INT32(* NDDS_Transport_Send_Fcn)(NDDS_Transport_Plugin *self, const NDDS_Transport_SendResource_t *sendresource_in, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in, const NDDS_Transport_Buffer_t buffer_in[], RTI_INT32 buffer_count_in, void *reserved)

Synchronous gather send. Send multiple buffers by means of a previously created SendResource to a pre-registered destination.

When this method is invoked, the transport needs to send all buffers contained in the gather-array (concatenated in the order given) as a single message to the given address/port.

When this method returns, NDDS will assume that the message has been sent and that it can resuse the buffers.

Precondition: This is the contract that NDDS has when calling this method.

sendresource_in is linked to dest_address_in/dest_port_in. In other words, create_sendresource_srEA() or share_sendresource_srEA() were successfully called with the given dest_address_in/dest_port_in which returned the corresponding handle now passed in sendresource_in.

The number of buffers in the array, buffer_in[], is smaller or equal to the gather_send_buffer_count_max property of the Transport Plugin.

The total size of all buffers in the buffer_in[] is smaller or equal to the message_size_max property of the Transport Plugin.

The size of each buffer in buffer_in[] is strictly larger than 0.

Postcondition: These are the responsibility of the Transport-Plugin implementation.

After this call returns, the Transport Plugin is not allowed to use any references to the buffers that were passed in.

If the call returns 1, the Transport Plugin did not encounter any unexpected problems in sending the message. This does not necessarily imply the message has been or will be received or that it has even appeared on the communication medium.

If the call returns 0, the Transport Plugin has encountered an unexpected problem and it knows that the message has NOT been sent.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
sendresource_in	<<in>> A SendResource previously created by the Transport Plugin's NDDS_Transport_Create_SendResource_Fcn_srEA.
dest_address_in	<<in>> Destination address to which the message should be sent.
dest_port_in	<<in>> Destination port to which the message should be sent.
transport_priority_in	<<in>> Transport priority with which the message should be sent.
buffer_in	<<in>> An array of buffers whose contents together form the message to be send. The transport must send the data contained in buffer_in[0] to buffer_in[buffer_count_in-1].
buffer_count_in	<<in>> The number of buffers in the buffer_in array. This number will not be not be greater than the `gather_send_buffer_count_max` specified by the transport property.

Returns: 1 on success; 0 otherwise.

MT Safety:: multi-thread safe This method must be written to be multi-thread safe. The Transport Plugin must allow multiple thread to call send() concurrently on the same instance of the plugin with the same SendResource.

See Also: The Sending Side; NDDS_Transport_Property_t::gather_send_buffer_count_max

typedef RTI_INT32(* NDDS_Transport_Recv_Fcn_rEA)(NDDS_Transport_Plugin *self, NDDS_Transport_Message_t *message_out, const NDDS_Transport_Buffer_t *buffer_in, const NDDS_Transport_RecvResource_t *recvresource_in, void *reserved)

Blocking-receive call to retrieve messages received by a Transport Plugin.

The Transport Plugin must implement this method as a blocking call. When this call is made, if there are messages available, one will be taken in FIFO order and returned to NDDS in the message_out structure. If there are no messages available, then this method should block until one becomes available or until it is unblocked with the unblock_receive_rrEA() call, see Blocking Receives.

The Transport Plugin can copy the message to be returned into the buffer_in structure passed to this method or return the message in an internal buffer to be loaned to the NDDS core. In either case, the message_out->buffer.pointer field should be set to point at the memory where the message is stored and the corresponding length field set to the size of the returned message.

Precondition: This is the contract that NDDS has when calling this method.

recvresource_in was previously been created by the instance of the Transport Plugin using its create_recvresource_srEA() method.

message_out is not NULL.

If the NDDS_Transport_Property_t::properties_bitmap does not have the NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED bit set, then buffer_in will be at least NDDS_Transport_Property_t::message_size_max bytes long to hold the returned message.

Postcondition: These are the responsibility of the Transport-Plugin implementation.

If the NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED bit of the NDDS_Transport_Property_t::properties_bitmap is set, then this method will not use the buffer_in parameter to store the message to be returned.

If the Transport Plugin is loaning an internal buffer and returning it using the message_out parameter, then message_out->loaned_buffer_param is set to something other than -1. Usually it will be set to point at some additional information needed by the Transport Plugin when the loaned buffer is returned.

If the Transport Plugin is not loaning a buffer, and message_out refers to the buffer_in parameter instead, then message_out->loaned_buffer_param is set to -1.

There are 3 possible ways to return from this call:

Returns: 1 upon success and

message_out->buffer.length > 0, indicating that a valid message is being passed back to NDDS.

message_out->buffer.length == 0, indicating that the method is returning because it was unblocked by the unblock_receive_rrEA() call.

Returns: 0, indicating that there was an fatal failure in the transport such that subsequent calls to this method will also fail.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
message_out	<<out>> A message received by the transport will be passed to NDDS via this structure.
buffer_in	<<in>> A buffer that may be used by this method to store the message that is passed back to NDDS. If so, then appropriate fields of the message_out parameter will be setup to reference the contents of buffer_in.
recvresource_in	<<in>> A RecvResource previously created by the Transport Plugin's NDDS_Transport_Create_RecvResource_Fcn_rrEA.
reserved	<<in>> A parameter only to be used by NDDS builtin Transport Plugins.

MT Safety:: Does not need to be multithreaded-safe. NDDS will guarantees that only a single thread at a time will call receive for a specific instance of a Transport Plugin and recvresource_in.

See Also: NDDS_TransportPlugin_receiving; NDDS_TransportPlugin_loaning_receive

typedef void(* NDDS_Transport_Return_Loaned_Buffer_Fcn_rEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_RecvResource_t *recvresource_in, NDDS_Transport_Message_t *message_in, void *reserved)

Method used by NDDS to return a buffer loaned by a Transport Plugin in the receive_rEA() call to pass a received message to NDDS.

High-performance transports can lend an internal buffer to NDDS to avoid copying memory when received messages are passed to NDDS.

If a buffer is lent, then to avoid running out of memory in the transport, it is crucial that NDDS will return the memory back to the transport as soon as NDDS is finished processing the message.

Currently, the Transport Plugin is guaranteed that for a RecvResource, this method will be called for a message previously loaned before NDDS tries to receive another message from the RecvResource. In addition, only one NDDS thread will try to collect received messages from a RecvResource at a time.

In future versions of NDDS, when there may be a thread pool used to service the same RecvResource. In that case, then the contract for calling this method may need to change to accomodate thread safety.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
recvresource_in	<<in>> A RecvResource previously created by the Transport Plugin's NDDS_Transport_Create_RecvResource_Fcn_rrEA.
message_in	<<in>> A message containing a buffer that was previously loaned by the Transport Plugin.
reserved	<<in>> A parameter only to be used by NDDS builtin Transport Plugins.

See Also: The Optional "Loaned-Buffer" Mechanism

typedef RTI_INT32(* NDDS_Transport_Unblock_Recv_Fcn_rrEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_RecvResource_t *recvresource_in, void *reserved)

Called by NDDS to unblock a thread blocked on receive_rEA() or otherwise return immediately when receive_rEA() is called.

Postcondition

When this method returns, either a thread that is currently blocked on receive_rEA() (for the same recvresource_in) will wakeup and return with a 0-byte message, or the next call by NDDS to receive_rEA() (for the same recvresource_in) will immediately return with a 0-byte message.

This method is used during the shutdown phase of a DDS participant.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
recvresource_in	<<in>> A RecvResource previously created by the Transport Plugin's NDDS_Transport_Create_RecvResource_Fcn_rrEA.
reserved	<<in>> A parameter only to be used by NDDS builtin Transport Plugins.

See Also: NDDS_TransportPlugin_blocking_receives

typedef RTI_INT32(* NDDS_Transport_Create_RecvResource_Fcn_rrEA)(NDDS_Transport_Plugin *self, NDDS_Transport_RecvResource_t *recvresource_out, NDDS_Transport_Port_t *recv_port_inout, const NDDS_Transport_Address_t *multicast_address_in, RTI_INT32 reserved)

Called by NDDS to initialize the Transport Plugin to receive messages for a given port and/or multicast address. A handle to the transport-specific data structure (RecvResource) used by NDDS to collect received messages from this plugin is returned.

When this method is called, NDDS expects the Transport Plugin to prepare to receive messages on its interfaces for a particular port and possibly multicast address. So the Transport Plugin must do what it needs to do for the specific transport hardware/software to begin receiving messages. Generally, all plugin implementations will create an internal queue to buffer messages that are received, but have not yet been collected by NDDS via the receive_rEA() call.

The recvresource_out parameter is a way for the Transport Plugin to give NDDS a handle to information (data structure) that NDDS needs to pass back to the Transport Plugin when it wants to collect the received messages. What is in the data structure will be specific to every Transport-Plugin implementation.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
recvresource_out	<<out>> A RecvResource that is created by this call will be returned through this parameter.
recv_port_inout	<<inout>> A pointer to a port. NDDS is asking the Transport Plugin to assign a port, then the input value must be NDDS_TRANSPORT_PORT_INVALID.
multicast_address_in	<<in>> A multicast address on which NDDS would like the transport to receive messages. May be NULL if NDDS is not asking the transport to receive messages on a multicast address.
reserved	<<in>> Not currently used.

Precondition

When this method is called, NDDS may ask the Transport Plugin to create a RecvResource for a particular pair of values passed in for recv_port_inout and multicast_address_in. The values for (recv_port_inout, multicast_address_in) can be divided into one of three possible combinations, each one associated with a different request in how the Transport Plugin should create the RecvResource.

(valid port, NULL multicast address) : This requests the plugin to create a RecvResource to receive unicast messages on all of its interfaces for the specific port number passed in.

(NDDS_TRANSPORT_PORT_INVALID, NULL multicast address) : This requests the plugin to chose a port number (in addition to creating a RecvResource) on which to receive unicast messages on all of its interfaces. The chosen port number should be returned in the parameter recv_port_inout.

(valid port, valid multicast address ) : This requests the plugin to create a RecvResource to receive messages sent to the specific multicast address and port number combination passed in.

The combination (NDDS_TRANSPORT_PORT_INVALID, valid multicast address) will never be passed to this method by NDDS.

Postcondition: If successful, NDDS can invoke the receive_rEA() function using the returned RecvResource. Messages received by the Transport Plugin for the RecvResource are stored until receive_rEA() is called.

Returns: 1 on success

If the passed in value of recv_port_inout was NDDS_TRANSPORT_PORT_INVALID, the value of recv_port_inout will be set to the port that the Transport Plugin has arbitrarily selected.

Returns: 0 otherwise, and the contents of *recvresource_out is not valid.

See Also: The RecvResource Concept; NDDS_Transport_Destroy_RecvResource_Fcn_rrEA

typedef void(* NDDS_Transport_Destroy_RecvResource_Fcn_rrEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_RecvResource_t *recvresource_in)

Called to destroy a RecvResource previously created with NDDS_Transport_Create_RecvResource_Fcn_rrEA.

Precondition

The RecvResource was successfully created by NDDS_Transport_Create_RecvResource_Fcn_rrEA.

NDDS guarantees that no other thread is using the RecvResource nor blocked on the RecvResource.

All buffers loaned by the RecvResource through the receive_rEA() call will have been returned by NDDS.

Postcondition

The Transport Plugin has reclaimed or released all resources dedicated to this RecvResource. Any memory allocated specifically to support the RecvResource has been freed. NDDS will not use the RecvResource again.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
recvresource_in	<<in>> The RecvResource to be destroyed.

See Also: NDDS_Transport_Unblock_Recv_Fcn_rrEA

typedef RTI_INT32(* NDDS_Transport_Share_RecvResource_Fcn_rrEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_RecvResource_t *recvresource_in, const NDDS_Transport_Port_t recv_port_in, const NDDS_Transport_Address_t *multicast_address_in, RTI_INT32 reserved)

Called to see if an existing RecvResource can be shared to receive messages on a different port/multicast address.

This method is called by NDDS when it needs to associate a RecvResource with a port/multicast address combination. NDDS will first try to share existing RecvResources to receive messages for the new port/address. Only if no existing RecvResources can be shared, will NDDS call create_recvresource_rrEA() to create a new RecvResource for the port/address.

This method must be idempotent. That is, it must succeed if it is called with a port/address combination that have already been associated with the RecvResource (either the RecvResource was created for the port/address combination or was previously shared). So successive calls to this method with the same parameters must succeed if the first call succeeds.

Precondition: The parameter recv_port_in will not have the value NDDS_TRANSPORT_PORT_INVALID.

Postcondition

If the RecvResource can be shared so that NDDS can use it to receive messages for the port/address combination passed in, then the Transport Plugin must take whatever necessary action, if any, to prepare to receive those messages.

It is up to each transport implementation to decide what it needs to do to share a RecvResource. Some transports may not need to do anything. Others may never be able to share a RecvResource if the ports are different. It is recommended for the ones that can share a RecvResource that all messages that the RecvResource has been enabled to receive are stored in a single FIFO queue no matter what port/address it was sent to. Each time receive_rEA() is called, NDDS should get a message from the queue.

A notable side effect of sharing or not is comes from the fact that each RecvResource is only serviced by a single NDDS thread at a time. If a new RecvResource is created, than a new NDDS thread will be started and added to the thread pool. If a RecvResource is shared, then no new NDDS threads will be started.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
recvresource_in	<<out>> A RecvResource that was previously created.
recv_port_in	<<in>> A port number on which NDDS would like the transport to receive messages. This number is guaranteed not to be NDDS_TRANSPORT_PORT_INVALID.
multicast_address_in	<<in>> A multicast address on which NDDS would like the transport to receive messages. May be NULL if NDDS is not asking the transport to receive messages on a multicast address.
reserved	<<in>> Not currently used.

Returns: 1 if the RecvResource has been shared to receive for the recv_port_in/multicast_address_in combination; 0 if the RecvResource cannot be shared

See Also: The RecvResource Concept; NDDS_Transport_Create_RecvResource_Fcn_rrEA

typedef RTI_INT32(* NDDS_Transport_Unshare_RecvResource_Fcn_rrEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_RecvResource_t *recvresource_in, const NDDS_Transport_Port_t recv_port_in, const NDDS_Transport_Address_t *multicast_address_in, RTI_INT32 reserved)

Called to unshare a RecvResource that was previously successfully shared for a port/address.

A Transport Plugin does not need to supply a valid implementation of this method for the correct operation of NDDS. NDDS only calls this method to give the Transport Plugin an opportunity to release resources that may not be needed if NDDS does not expect to receive any more messages for a particular port/address.

Only those implementations that care about optimum resource usage will need to implement a working version of this method. For other implementations, after this method returns, the RecvResource can still be enabled to receive messages for the passed in port/address without affecting the proper operation of NDDS.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
recvresource_out	<<out>> A pointer to a RecvResource that was previously created and shared for the passed in recv_port_in/multicast_address_in combination.
recv_port_in	<<in>> A port number for which the RecvResource has been used to receive messages. This number is guaranteed not to be NDDS_TRANSPORT_PORT_INVALID.
multicast_address_in	<<in>> A multicast address for which the RecvResource has been used to receive messages. May be NULL if the request is to unshare an unicast port.
reserved	<<in>> Not currently used.

Returns: 1 on success; 0 otherwise.

typedef RTI_INT32(* NDDS_Transport_Create_SendResource_Fcn_srEA)(NDDS_Transport_Plugin *self, NDDS_Transport_SendResource_t *sendresource_out, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in)

Called by NDDS to initialize the Transport Plugin to send messages to the destination as defined by the passed in address/port. A handle to the transport-specific data structure (SendResource) used by NDDS to send messages with this plugin is returned.

When this method is called, NDDS expects the Transport Plugin to prepare to send messages through its interfaces for a particular destination as defined by the address and port that are passed as parameters. So the Transport Plugin must do what it needs to do to initialize the sending side of the specific transport hardware/software. If the address/port is a destination that the Transport Plugin cannot reach, then this call should fail to create a SendResource.

The transport-plugin implementor can think of a SendResource as the collection of all of the data/structures needed by the plugin's send() function to send data to the address/port/transport_priority combination. This function should create those data structures and otherwise initialize the Transport Plugin to do so.

For Transport Plugins based on physical transports that require a connection to be established between sending and receiving applications before data can be sent, this call should return a partially initialized SendResource if the receiving side is not yet ready to accept connections. For those transports, the connection state of the SendResource should be checked and completed in the send() call if the connection was not successfully established in thsi method. See Sending on Connection-Oriented Transports before the Receiver is Initialized for more discussion.

The sendresource_out parameter is a way for the Transport Plugin to give NDDS a handle to information (data structure) that NDDS needs to pass back to the Transport Plugin when it wants to send a messages with the plugin. What is in the data structure will be specific to every Transport-Plugin implementation.

The transport_priority_in parameter is configured at the DDS level, a QoS of the DataWriter, and passed by NDDS to the Transport Plugin when it needs to create a SendResource for the DataWriter. How the value of transport_priority_in is interpreted or used by a Transport Plugin will be specific to each implementation. Most implementation will ignore the value altogether.

Others may use the value to set a quality or class of service (QoS, CoS) so that messages sent by this plugin to the particular destination will have a higher or lower priority.

Precondition

dest_address_in is not NULL.

dest_port_in is not NDDS_TRANSPORT_PORT_INVALID.

Postcondition

If 1 is returned, NDDS can use the returned SendResource in the plugin's send() call to send messages.

If 0 is returned, the transport has determined that it cannot send to the given destination and no SendResource was created.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
sendresource_out	<<out>> A SendResource that is created by this call will be returned through this parameter.
dest_address_in	<<in>> The destination address of an interface to which a message will be sent.
dest_port_in	<<in>> A destination port.
transport_priority_in	<<in>> Value configured in the DataWriter and passed through NDDS without modification to the Transport Plugin.

Returns: 1 on success; 0 otherwise.

See Also: NDDS_TransportPlugin_sendresource; NDDS_Transport_Destroy_SendResource_Fcn_srEA

typedef void(* NDDS_Transport_Destroy_SendResource_Fcn_srEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_SendResource_t *sendresource_in)

Called to destroy a SendResource previously created with NDDS_Transport_Create_SendResource_Fcn_srEA.

Precondition

The SendResource was successfully created by NDDS_Transport_Create_SendResource_Fcn_srEA.

The SendResource is not being used and will not be used by NDDS in any calls to the Transport Plugin's API like send().

Postcondition

The Transport Plugin has reclaimed or released all resources dedicated to this SendResource. Any memory allocated specifically to support the SendResource has been freed. NDDS will not use the SendResource again.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
sendresource_in	<<in>> A SendResource previously created by the Transport Plugin's NDDS_Transport_Create_SendResource_Fcn_srEA.

typedef RTI_INT32(* NDDS_Transport_Share_SendResource_Fcn_srEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_SendResource_t *sendresource_in, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in)

Called to see if an existing SendResource can be shared to send messages to a different destination (address/port).

This method is called by NDDS when it needs to associate a SendResource with a destination (address/port). NDDS will first try to share existing SendResources to send messages for the new address/port. Only if no existing SendResources can be shared, will NDDS call create_sendresource_srEA() to create a new SendResource for the address/port.

This method must be idempotent. That is, it must succeed if it is called with an address/port combination that have already been associated with the SendResource (either the SendResource was created for the address/port combination or was previously shared). So successive calls to this method with the same parameters must succeed if the first call succeeds.

For those Transport Plugin implementations that supports the idea of a transport priority, then the transport_priority_in parameter should be used in determining whether or not a SendResource can be used to send at the given priority. When the SendResource was created, the plugin may have used a value of the transport priority during the initialization of the SendResource (whatever that means to the implementation).

The value passed in transport_priority_in may or may not be compatible with the priority with which the SendResource was originally configured, even if the destination (address/port) are compatible. So for some Transport Plugin implementations, this method may determine that it was not able to share a SendResource because of incompatible transport priorities.

Precondition: The dest_address_in is a valid address and dest_port_in does not have the value NDDS_TRANSPORT_PORT_INVALID.

Note, dest_address_in may be a multicast address.

Postcondition

If the SendResource can be shared so that NDDS can use it to send messages to the address/port combination and honoring the requested transport priority (if applicable), then the Transport Plugin must take whatever necessary action, if any, to prepare to send those messages.

It is up to each transport implementation to decide what it needs to do to share a SendResource. Some transports may not need to do anything.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
sendresource_out	<<out>> A SendResource that was previously created.
dest_address_in	<<in>> The destination address of an interface to which a message will be sent. The destination address may be a multicast address.
dest_port_in	<<in>> A destination port.
transport_priority_in	<<in>> Value configured in the DataWriter and passed through NDDS without modification to the Transport Plugin.

Returns: 1 if the SendResource has been shared to send messages to the dest_address_in/dest_port_in/transport_priority_in combination; 0 if the SendResource cannot be shared

See Also: NDDS_TransportPlugin_sendresource

typedef const char*(* NDDS_Transport_Get_Class_Name_Fcn_cEA)(NDDS_Transport_Plugin *self)

Returns the string class name of the transport.

A Transport Plugin has a class name which is used to refer to the transport when constructing peer locators. For example, the string "shmem" in "shmem://" or "udpv4" in "5@udpv4://192.168.1.1". See NDDS_DISCOVERY_PEERS for more information on peer locators. This method is used by the transport to declare this class name.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.

Invariant: All instances of a Transport Plugin class should return the same string.

Returns: A pointer to a string constant. The memory is owned by the transport plugin; the caller should not overwrite or deallocate the string.

typedef RTI_INT32(* NDDS_Transport_Unshare_SendResource_Fcn_srEA)(NDDS_Transport_Plugin *self, const NDDS_Transport_SendResource_t *sendresource_in, const NDDS_Transport_Address_t *dest_address_in, const NDDS_Transport_Port_t dest_port_in, RTI_INT32 transport_priority_in)

Called to unshare a SendResource that was previously successfully shared for an address/port.

A Transport Plugin does not need to supply a valid implementation of this method for the correct operation of NDDS. NDDS only calls this method to give the Transport Plugin an opportunity to release resources that may not be needed if NDDS does not expect to send any more messages for a particular address/port/transport_priority combination.

Only those implementations that care about optimum resource usage will need to implement a working version of this method. For other implementations, after this method returns, the SendResource can still be enabled to send messages for the passed in address/port/transport_priority combination without affecting the proper operation of NDDS.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
sendresource_out	<<out>> A SendResource that was previously created and shared for the passed in dest_address_in/dest_port_in/transport_priority_in combination.
dest_address_in	<<in>> The destination address of an interface to which a message was being sent. The destination address may be a multicast address.
dest_port_in	<<in>> A destination port.
transport_priority_in	<<in>> Value configured in the DataWriter and passed through NDDS without modification to the Transport Plugin.

Returns: 1 on success; 0 otherwise.

typedef RTI_INT32(* NDDS_Transport_String_To_Address_Fcn_cEA)(NDDS_Transport_Plugin *self, NDDS_Transport_Address_t *address_out, const char *address_in)

Called to convert a Transport-Plugin-specific string representation of an address to an IPv6 address representation.

A Transport Plugin implementation may define how to interpret addresses stored as a string, for example, "192.168.0.1", "server1", "com1", into a NDDS_Transport_Property_t::address_bit_count (<= 16-octets) numerical address that is meaningful to the transport.

This method should take the string passed in as address_in and map it or otherwise convert it to an NDDS_Transport_Property_t::address_bit_count (<= 16-octets) bit value that can be used to address interfaces of the Transport Plugin class.

The method may be passed address strings that it cannot map or convert. For example, if "server1" is passed to a IP-based Transport Plugin, then this method may call gethostbyname() to try to convert it into an IPv4 address (which subsequently will be returned as a 16-octet number). If "server1" is not in the machines's host table or cannot be looked up via DNS/NIS, then string_to_address_cEA() function will fail to convert the string to an address.

Precondition: address_out, and address_in are not NULL.

Postcondition

If address_in can be interpreted by the Transport Plugin then it will return the corresponding numerical address in address_out; otherwise address_out will be unaltered.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
address_out	<<out>> A non-NULL placeholder to return the IPv6 address representation.
address_in	<<in>> A non-NULL character string (NULL terminated), that represents an address in a transport class specific format.

Invariant: All instances of a Transport Plugin class should output a consistent answer (or return 0).

Returns: 1 if address_out contains a 16-octet numerical address corresponding to address_in.; 0 otherwise.

typedef RTI_INT32(* NDDS_Transport_Get_Receive_Interfaces_Fcn_cEA)(NDDS_Transport_Plugin *self, RTI_INT32 *found_more_than_provided_for_out, RTI_INT32 *interface_reported_count_out, NDDS_Transport_Interface_t interface_array_inout[], RTI_INT32 interface_array_size_in)

Called to retrieve a list of interfaces that can be used to receive messages through this Transport Plugin.

This method is called by NDDS to get a list of interfaces (addresses) that applications should use if they want to send messages to this application via the Transport Plugin. That is the reason that this method is called get_receive_interfaces_cEA(). It is assumed that the interfaces that the Transport Plugin may use to send messages is the same set as returned by this method.

If a Transport Plugin implementation can be configured to selectively use interfaces, then it is important that this method returns a list of interfaces that the Transport Plugin on which it can actually receive messages. Interfaces that are disabled, "down", restricted from use, or otherwise incapable of receiving messages should not be returned by this method.

Precondition

The array interface_array_inout[] contains at least interface_array_size_in elements. interface_reported_count_out and found_more_than_provided_for_out must be non-NULL.

Postcondition

No more than interface_array_size_in interface descriptions are stored in the array interface_array_size_inout[]; and the number of interfaces that have been stored is reported in interface_reported_count_out.

If the Transport Plugin has more interfaces than can be stored in the array, actual number is greater than interface_array_size_in, then found_more_than_provided_for_out is set to 1.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
found_more_than_provided_for_out	<<out>> Return parameter to indicate whether there were more interfaces than reported.
interface_reported_count_out	<<out>> Return parameter holding the number of interfaces returned in `interface_array_inout`.
interface_array_inout	<<inout>> An array of interface structures containing at least `interface_array_size_in` elements.
interface_array_size_in	<<in>> Number of elements in `interface_array_inout` (> 0).

Returns: 1 on success

If the Transport Plugin instance has more interfaces than interface_array_size_in, then *found_more_than_provided_for_out = 1.

Returns: 0 otherwise.

typedef RTI_INT32(* NDDS_Transport_Register_Listener_Fcn_cEA)(NDDS_Transport_Plugin *self, NDDS_Transport_Listener *listener_in)

Called by NDDS to register a set of callback functions that should be called by the Transport Plugin instance when it detects specific dynamic changes in its state.

Although not fully implemented in this release, NDDS is designed so that a Transport Plugin can notify NDDS of dynamic changes in its state that may affect its ability to send or receive messages. Dynamic changes that a Transport Plugin may detect include changes to the number of interfaces that it can manage or interfaces going "up" or "down".

Currently, the only callback in the listener is for changes to the state of interfaces of a Transport Plugin. When called back, NDDS could requery the plugin for a list of interfaces and then make appropriate internal adjustments if needed to accomodate interface changes.

Attention: Currently NDDS does not register listeners, and thus Transport Plugins may implement this method as a dummy function.

Postcondition: If the Transport Plugin supports dynamic change detection then it should return 1 and when dynamic changes occur, it should call back the appropriate function in the listener that was passed in.

Consecutive calls to this method will replace the listener with the one passed in. A NULL listener_in means that NDDS does not want to be called back.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
listener_in	<<in>> A listener containing callback functions.

Returns: 1 if the the Transport Plugin supports detection of dynamic changes and the listener has been set.; 0 otherwise.

See Also: NDDS_TransportPlugin_addressses

typedef void(* NDDS_Transport_Delete_Fcn_cEA)(NDDS_Transport_Plugin *self, void *reserved)

Method used to delete an instance of a Transport Plugin.

This is the destructor method for a NDDS_Transport_Plugin.

However, it is not automatically called by NDDS for user transports.

NDDS will only delete the Transport Plugins that it creates. If an user application instances a Transport Plugin, either a custom Transport Plugin or a NDDS builtin Transport Plugin that is custom configured, then the user application must explicitly delete the Transport Plugin.

Deletion of a Transport Plugin must happen only after the DDS participant with which the Transport Plugin has been registered has deleted, see .

Precondition: All SendResources and RecvResources created by the Transport Plugin instance have been destroyed.

Postcondition: All resources and memory used by the Transport Plugin have been released, deleted or freed including the plugin instance itself.

Parameters

self	<<in>> A pointer to the instance of the Transport Plugin.
reserved	<<in>> Used only by builtin NDDS Transport Plugins.

Data Structures

Typedefs

Detailed Description

Typedef Documentation