API Usage Examples

Code Examples. More...

Code Examples.

The following example shows how to initialze, create a message queue, sending and receiving messages on it and finaly deleting it.

As a first step, the application has to register itself with the Message Service. For this the application has to call saMsgInitialize() API. This API will return a message handle for the client. And all the subsequent communication with Message Service will be needing this message handle.

SaAisErrorT retCode = SA_AIS_OK;  // This variable is to catch the error
                                  // codes returned by APIs of Message
                                  // Service.
SaMsgHandleT msgHandle = 0;  // This will be having a Message handle if
                             // the saMsgInitialize() succeeds and it
                             // should be used for all subsequent
                             // interactions with Message Service.
SaMsgCallbacksT msgCallback = {  // For registering the Application
                                 // Callbacks.
    .saMsgQueueOpenCallback  = NULL,
    .saMsgQueueGroupTrackCallback = NULL,
    .saMsgMessageDeliveredCallback = NULL,
    .saMsgMessageReceivedCallback = NULL
};
SaVersionT msgVersion = {  // The version of SAF Message Serivce, which
                           // the application is compatible with.
    .releaseCode = 'B',
    .majorVersion = 0x1,
    .minorVersion = 0x1
};

retCode = saMsgInitialize(&msgHandle, &msgCallback, &msgVersion);
if( retCode != SA_AIS_OK)
{
    // The Message Service initialization for the client failed. No
    // Message Service related operations can be performed further.
}

Now opening a Message Queue. The saMsgInitialize() must be called before calling any of the SAF Message Service APIs. This is needed by the Message Server for identifying the client. And for the same reason the Message Handle needs to be passed to saMsgQueueOpen() API.

SaNameT queueName = {  //  The Name of the Queue that is to be opened.
    .length = strlen("queueName"),
    .value  = "queueName"
};
SaMsgQueueCreationAttributesT creationAttributes = { //Queue Attributes.
    .creationFlags = 0, // 0 indicates Non-Persistent Queue and
                        // 1 indicates Persistent.
    .size = {10, 10, 10, 10}, // The sizes of the Priorirty Queues in
                              // the Actual Queue, which is going to be
                              // opened.
    .retentionTime = 0 // Retention Time of the Queue. The queue will
                       // be available for "retentionTime" nanoseconds
                       // even closing the Queue.
};
SaMsgQueueHandleT queueHandle; // If the queue is opened successully then
                               // the queue handle will be returned in
                               // this.

retCode = saMsgQueueOpen(
                 msgHandle,           // Message Handle got from
                                      // saMsgInitialize() API.
                 &queueName,          // Queue Name to be opened.
                 &creationAttributes, // Queue Attributes.
                 SA_MSG_QUEUE_CREATE, // Queue open mode.
                 SA_TIME_MAX,         // within this time saMsgQueueOpen()
                                      // should return, either success or
                                      // failure.
                 &queueHandle);       // Handle for the queue if opened
                                      // successfully.
if(msgError != SA_AIS_OK)
{
    // The saMsgQueueOpen() failed. The Message Service could not open 
    // the queue. 
}

Here we can see how a message can be sent to a destination. For this the application must initialize the Message Service client.

SaNameT senderName = {  // The source/sender's queue name. 
    .length = strlen("senderQ"),
    .value  = "senderQ"
};
SaNameT receiverName = {  // The destination/receiver's queue name. 
    .length = strlen("receiverQ"),
    .value  = "receiverQ"
};
char sendData[20] = "Hello World"; // An example message.
SaMsgMessageT   senderMessage = {
    .type = 0,    // Type of the message.
    .version = 0, // version of the Message Service.
    .size = 20,   // Size of the message to be sent.
    .senderName = &senderName, // Senders Queue Name.
    .data = sendData, // The actual message.
    .priority = SA_MSG_MESSAGE_HIGHEST_PRIORITY // Message Priority.
};

// The Message for this client should be initialized through
// saMsgInitialize().

// The Sender's Message must be opened here. And the receiver's queue need
// not be opened. It will opened by the receiver.


retCode = saMsgMessageSend(
    msgHandle,
    &receiverName,
    &senderMessage,
    SA_TIME_ONE_SECOND
    );
if(CL_OK != retCode)
{
    // Message Send failed. The error code will be in "retCode".
}

On the receiver side, the receiver must have opened the "receiverQ". Only then it can receive the message sent to it by a sender.

char receiveData[20] = {0};
SaMsgMessageT receiverMessage = {
    .type = 0,    // Type of the message.
    .version = 0, // Version of the Message Service.
    .size = 20,   // Size of the message buffer.
    .senderName = &senderName, // Sender's Queue Name.
    .data = receiveData, // The Message buffer.
    .priority = SA_MSG_MESSAGE_HIGHEST_PRIORITY // Message Priority.
};
    
// The Message Service for this client must be initialized through
// saMsgInitialize() API.

// The receiver message queue must be opened by the application here.

retCode = saMsgMessageGet(
    recvQueueHandle,
    &recevierMessage,
    NULL, 
    &senderId,
    SA_TIME_TEN_SECOND);
if(retCode != SA_AIS_OK)
{
    // Message Receive failed. The error code will be in "retCode".
}

Closing the Message Queue close will make the queue handle unusable. So no subsequent operations on the queue can be performed. The queue continues to exist for the "retentionTime" nano-seconds, if the queue is a non-persistent queue. And for the persistent ones it will exist till the queue is unlinked using the saMsgQueueUnlink() API.

retCode = saMsgQueueClose(queueHandle);
if(CL_OK != retCode)
{
    // Failed to delete the queue pointed by queueHandle. The error code
    // will be in "retCode".
}

The saMsgFinalize() will close the application's Message handle and the Message Service will do all the cleanups releated to that client.

retCode = saMsgFinalize(msgHandle);
if(CL_OK != retCode)
{
     // Failed to Finalize the Message Service. 
}