API Usage Examples

Code Examples. More...

Code Examples.

The following example shows how to create a commport, sending and receiving messages on it and then deleting it.

As a first step, a communication port is created. For creating a commport we can specify a required communication port id, if the commport is going to serve as a well known server. This can be chosen from clIocServices.h file. If 0 is passed for commPortId then the IOC will chose one commomuincation port id for the application. For sending and receiving through this communication port the communication handle should be used.

ClRcT retCode = CL_OK;
ClIocCommPortHandleT commPortHandle; // This will filled and returned
                                     // on successful creation of
                                     // communication port.

ClUint32T commPortId = 0x8888; // It can be any port number within the
                               // range specified in clIocServices.h.
ClUint32T commMode = CL_IOC_RELIABLE_MESSAGING;

retCode = clIocCommPortCreate(commPortId, commMode, &commPortHandle );
if(CL_OK != retCode) {
    // Most of the times the error will occur due to Less memory OR
    // If the port is already being used by some other component.
    // Cannot do any send and receive with this communication port in
    // this application.
} 

Here we can see how a message can be sent to a destination. The protocol field is a must for sending a packet, and it should be chosen from clIocProtocols.h file. The data to be sent should be passed as a buffer message. And the receiver address can be a physical, logical or a multicast address.

ClBufferHandleT         sendBuffer = 0;
ClUint32T               protocol;
ClIocAddressT           receiverAddress ;
ClIocSendOptionT        sendOption = {0};

// Create and fill the sendBuffer here.
// Fill the receiverAddress here.

protocol = USER_PROTOCOL; // This is information for the receiver
                          // to analyse the sendBuffer. This should
                          // be within the proper range specified in
                          // clIocProtocol.h file.
sendOption.priority = 0;  // You can specify the priority of the
                          // message.
sendOption.timeout = CL_IOC_TIMEOUT_FOREVER; // Send will return if
                          // it is able to send the whole message or
                          // if the timeout occurs, whiever is the
                          // earliest.

retCode = clIocSend(commPortHandle, 
                            sendBuffer, 
                            protocol,
                            &receiverAddress,
                            &sendOption);
if(CL_OK != retCode)
{
    // IOC send failed with error code in "retCode"
}

The clIocReceive() call will block on the commport for receiving a message. The call expects a valid buffer message handle to receive the data. On receiving some data the IOC unblocks the receiver thread, which is blocked on the commport. All the information relating to the message received( like sender info, length of the message, protocol for analysing the message), will be present in recvParam.

ClIocRecvOptionT recvOption;
ClIocRecvParamT  recvParam;

// Create a recvBuffer for holding the receiver message.

recvOption.timeout = CL_IOC_TIMEOUT_FOREVER; // Timeout within which
                          // the IOC should unblock the receiver
                          // thread with or without a message.

retCode = clIocReceive(commPortHandle,
                       recvOption,
                       recvBuffer,
                       recvParam);

if(CL_OK != retCode)
{
    // IOC receive failed with error code in "retCode"
}

// - recvParam.priority is the priority of the with which the sender
// sent the message.
// - recvParam.protoType is the protocol of the message with which the
// send and the receiver are communicating.
// - recvParam.length is the length of the received message.
// - recvParam.srcAddr is the address of the sender of the message.

For deleting a commport a valid commPortHandle must be passed. And before calling this API we need make sure that no thread is waiting for any data on this commport.

retCode = clIocCommPortDelete(commPortHandle);
if(CL_OK != retCode)
{
    //Communication deletion failed.
}