Service connections in JAUS are a publish-subscribe mechanism for exchanging data between components (See the JAUS reference architecture for a full description of service connections). This tutorial describes how to create a service connection to receive data from another component. In OpenJAUS, these are referred to as incoming service connections, because the messages are flowing into the subscribing component.

Incoming service connections are easy to manage because they only require the use of two functions. One function establishes the service connection and the other terminates it. Often the component requires the incoming connection in order to operate and usually never needs to explicitly terminate the connection. In this case only the establish function is needed. The component framework automatically terminates any incoming connections upon destruction of the OjCmpt data structure.

The ojCmptEstablishSc() function takes several inputs in order to configure the incoming service connection. After the function is called and the component is running, the component will automatically attempt to establish the service connection. Once the connection is made, the received messages can then be processed by the component via its registered callback functions. This process is the same for both service connection and non-service connection messages (See Sending & Recieving Messages for details). The ojCmptEstablishSc() function returns an int reference handle to the service connection. This value can then be sent to the terminate function in order to discontinue that specific service connection. The example below shows how the ojCmptEstablishSc() function is used.

myIncSC = ojCmptEstablishSc( 
         myCmpt,                   // Reference to the component's OjCmpt data structure
         JAUS_REPORT_GLOBAL_POSE,  // Command code of the message being requested
         0xFF,                     // Requested presence vector of the desired message
         sourceAddress,            // JausAddress of the desired message source component
         5.0,                      // Repeat rate (Hz) at which the message is requested
         1.0,                      // Maximum allowed time (sec) between receiving these messages
         1);                       // Size of the FIFO queue to store the messages in

If a non-zero subsystemId is specified in the source address field, then the component assumes the source address is complete and it attempts to request the service connection from that exact address. Otherwise, the component performs a system lookup for the component location based on componentId in the source address. The lookup assumes that the desired source is within the same subsystem as the requesting component. If an exact address of a component residing on another subsystem needs to be obtained then the ojCmptLookupAddress() function can be used.

The queue size specified in the establish function call can be a positive integer or zero. A negative value will cause an error. If the value is zero then the maximum queue size is not limited.

In order to explicitly terminate an established service connection, the ojCmptTerminateSc() function is used. This function simply takes the service connection descriptor value that was returned by the ojCmptEstablishSc() function. The example below shows how it is called.

// Terminate the service connection
ojCmptTerminateSc(myCmpt, myIncSc);