Skip to main content

How to use Cloud SQS Library

danger

this is a legacy library and thus not supported by Toradex anymore. We recommend that you use the new libraries for all Toradex modules. Please see the Toradex CE Libraries and Code Samples for up-to-date information.


Amazon Simple Queue Service (Amazon SQS)​

Amazon SQS works by exposing Amazon’s web-scale messaging infrastructure as a web service. Any computer on the Internet can add or read messages without any additional software installation or special firewall configurations. The components of applications using Amazon SQS can run independently. They do not need to be on the same network, developed with the same technologies, or running at the same time. A queue can be created in 8 regions – US East (Northern Virginia), US West (Oregon), US West (Northern California), EU (Ireland), Asia Pacific (Singapore), Asia Pacific (Tokyo), Asia Pacific (Sydney), and South America (Sao Paulo). The message body can contain up to 64 KB of text in any format. Messages can be sent, received or deleted and can be retained in a queue for up to 14 days. They can also be sent and read simultaneously.

For more information, please refer to: http://aws.amazon.com/sqs/

Notes:

  • Use a small length Queue Name for fast response time.
  • Use only alphanumeric/underscore/hyphen characters to construct the Queue Name and avoid using special characters.
  • The system time of Colibri Modules should not be deviated by more than 15 minutes; otherwise AWS specific functions will return an error.

Open SQS Handle​

Before calling any other function, you should call SqsOpenQueue() with all the parameter inputs: AWS Access Id, AWS Secret Key, AWS Owner ID, AWS SqS Region / Path and queueName as detailed below:

  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
“SendQueue" is the name of the queue. You can choose any name.

if (!SqsOpenQueue(AWS_ACCOUNT_ACCESS_ID,
                  AWS_ACCOUNT_SECRET_KEY,
                  AWS_SQS_SINGAPORE_REGION,
                  AWS_ACCOUNT_OWNER_ID,
                  queueName,
                  &SendQueue))
{
    printf("SqsOpenQueue Fails: Error Code: ");
    printf("%d\n", GetLastError());
}

SendQueue handle will be used by all other function calls as a parameter input hereafter. 

Create a Queue in a Region​

The SqsCreateQueue() function is used to create a queue in a region.

  • Parameter input is SendQueue handle returned from the SqsOpenQueue() function call.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsCreateQueue(SendQueue))
{
    printf("SqsCreateQueue Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else
{
    printf("SqsCreateQueue Success\n");
}

Delete a Queue in a Region​

The SqsDeleteQueue() function is used to delete a queue in a region.

  • Parameter input is the SendQueue handle returned from the SqsOpenQueue() function call.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsDeleteQueue(SendQueue))
{
    printf("SqsDeleteQueue Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsDeleteQueue Success\n");
}

Get URL of a Queue in a Region​

The SqsGetQueueUrl() function is used to get URL of a queue in a region.

  • 1st Parameter is the SendQueue handle returned from the SqsOpenQueue() function call.
  • 2nd parameter is the pointer to the memory in which the function will put URL data if successful.
  • 3rd parameter is the size of the memory allocated for 2nd parameter.
  • It will return TRUE if successful or FALSE if the call fails, use the GetLastError() to get extended error details.

char queueUrlData[1024] = {0};

memset(queueUrlData, 0, 1024);
if (!SqsGetQueueUrl(SendQueue, queueUrlData, 255))
{
    printf("SqsGetQueueUrl Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsGetQueueUrl Success\n");
    printf("> %s\n", queueUrlData);
}

Get URL of a Queue in a Region​

The SqsGetQueueUrl() function is used to get the URL of a queue in a region.

  • 1st Parameter is the SendQueue handle returned from SqsOpenQueue() function call.
  • 2nd parameter is the prefix string. If it is say “t", the function will list all of the queue in a region starting with letter “t".
  • 3rd parameter is the path of the file in which data needs to be stored.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsListQueues(SendQueue, "", "\\queueList.xml"))
{
    printf("SqsListQueues Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsListQueues Success\n");
}

Find Queue from List Stored in a Local File​

The SqsFindQueue() function is used to get queue details, one by one, from the local file.

  • 1st Parameter is the path of the file in which the list data is stored.
  • 2nd parameter is the pointer to the memory in which data needs to be put by the function if successful.
  • 3rd parameter is the size of the memory allocated for the 2nd parameter.
  • 4th parameter is the pointer to the memory which holds value and gives the location of the next queue detail in the file. To find 1st queue from list, set this variable to zero.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

char queueListData[1024] = {0};
DWORD listQueueNextPointer = 0;

memset(queueListData, 0, 1024
if (SqsFindQueue("\\queueList.xml", queueListData, 1024, &listQueueNextPointer, listFilesize))  
{
    printf("> %s\n", queueListData);
}

To find the next queue call SqsFindQueue() again, this time don’t set listQueueNextPointer as 0


memset(queueListData, 0, 1024
if (SqsFindQueue("\\queueList.xml", 
                 queueListData,
                 1024,
                 &listQueueNextPointer,
                 listFilesize)) 
{
    printf("> %s\n", queueListData);
}

Send a Message to a Queue​

The SqsSendMessage() function is used to send a message to a queue.

  • 1st Parameter is the SendQueue handle returned from the SqsOpenQueue() function call.
  • 2nd parameter is the message.
  • 3rd parameter is the delay in seconds after which message will be allowed to be accessed by other function calls. The valid range is 0 – 10.
  • 4th parameter is the pointer to the memory which holds messageID returned by the function if successful.
  • 5th parameter is the size of the memory allocated for 4th parameter.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

char sendMessageID[100 + 1] = {0}; // 100 is the max string length of the message ID.

memset(sendMessageID, 0, 100 + 1); 
if (!SqsSendMessage(SendQueue,
                    "Hello, Message from Toradex Colibri.",
                    0, 
                    sendMessageID,
                    100 + 1)) // No Delay in delivery
{
    printf("SqsSendMessage Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsSendMessage Success, ");
    printf("MessageID: %s\n", sendMessageID);
}

Receive a Message from a Queue​

The SqsReceiveMessage() function is used to receive a message from a queue.

  • 1st Parameter is the SendQueue handle returned from the SqsOpenQueue() function call.
  • 2nd parameter is the attributeName. Valid String values: All | SenderId | SentTimestamp | ApproximateReceiveCount | ApproximateFirstReceiveTimestamp. For now it is just fixed to “ALL".
  • 3rd parameter is the maxNumberOfMessages (Maximum number of messages to return). Values are 1 to 10 (maximum). For now it is not required so you can put any number from 1 – 10.
  • 4th parameter is the duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a SqsReceiveMessage() request. For now it is just same as for the queue.
  • 5th parameter is the pointer to the memory in which the message will be put by the function if successful.
  • 6th parameter is messageID. It is a pointer to memory which is used to hold message ID returned by the function if successful.
  • 7th parameter is recieptHandle. It is a pointer to memory which is used to hold reciept handle returned by the function if successful. This is required when you need to delete a message from a queue.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

char receiveMessageBody[4096 + 1] = {0}; // to receive 4KB message only
char receiveMessageID[100 + 1] = {0};
char recieptHandle[1024 + 1] ={0}; //max size of the reciept handle is 1024

memset(receiveMessageBody, 0, 4096 + 1);
memset(receiveMessageID, 0, 100 + 1);
memset(recieptHandle, 0, 1024 + 1);
if (!SqsReceiveMessage(SendQueue,
                       "ALL",
                       10,
                       30,
                       receiveMessageBody,
                       receiveMessageID,
                       receiptHandle))
{
    printf("SqsReceiveMessage Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsReceiveMessage Success\n");
    printf("MessageID:%s\n", receiveMessageID);
    printf("Received Message: %s\n", receiveMessageBody);
    printf("RecieptHandle: %s\n", recieptHandle);
}

Delete a Message from a Queue​

The SqsDeleteMessage() function is used to delete a message from a queue.

  • 1st Parameter is the SendQueue handle returned from the SqsOpenQueue() function call.
  • 2nd parameter is the receiptHandle returned by function call to SqsReceiveMessage().
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsDeleteMessage(SendQueue, recieptHandle))
{
    printf("SnsDeleteMessage Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SnsDeleteMessage Success\n");
}

Change Message Visibility of a Message in a Queue​

The SqsChangeMessageVisibility() function is used to change message visibility.

  • 1st Parameter is the SendQueue handle returned from SqsOpenQueue() function call.
  • 2nd parameter is the recieptHandle returned by function call to SqsReceiveMessage().
  • 3rd parameter is the new visibility time value. The valid range is 0 – 900 (seconds).
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsChangeMessageVisibility(SendQueue, 
                                receiptHandle,
                                90)) // New Timeout setting
{
    printf("SnsChangeMessageVisibility Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SnsChangeMessageVisibility Success\n");
}

Get Queue Attributes​

The SqsGetQueueAttributes() function is used to get queue attributes.

  • 1st Parameter is the SendQueue handle returned from the SqsOpenQueue() function call.
  • 2nd parameter is the pointer to the memory which will hold the attribute data returned by the function if successful.
  • 3rd parameter is the size of the memory allocated for 2nd parameter.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

char queueAttributesData[1024] = {0};

memset(queueAttributesData, 0, 1024);
if (!SqsGetQueueAttributes(SendQueue, queueAttributesData, 1024))
{
    printf("SqsGetQueueAttributes Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsGetQueueAttributes Success\n");
    printf("> %s\n", queueAttributesData);
}

Set Queue Attributes​

The SqsSetQueueAttributes() function is used to set queue attributes.

  • 1st Parameter is the SendQueue handle returned from the SqsOpenQueue() function call.
  • 2nd parameter is attribute type. Valid values are from 1 to 4 and you can use macros:

* #define QUEUE_ATTRIBUTE_VISIBILITY_TIMEOUT        1
* #define QUEUE_ATTRIBUTE_MAXIMUM_MESSAGE_SIZE      2
* #define QUEUE_ATTRIBUTE_MESSAGE_RETENTION_PERIOD  3
* #define QUEUE_ATTRIBUTE_DELAY_SECONDS             4

  • 3rd parameter is the value associated with attribute type:
  • VisibilityTimeout— An integer representing seconds from 0 to 43200 (12 hours). The default for this attribute is 30 seconds.
  • MaximumMessageSize— An integer from 1024 bytes (1 KB) up to 65536 bytes (64 KB). The default for this attribute is 65536 (64 KB).
  • MessageRetentionPeriod— An integer representing seconds, from 60 (1 minute) to 1209600 (14 days). The default for this attribute is 345600 (4 days).
  • DelaySeconds— An integer representing seconds from 0 to 900 (15 minutes). The default for this attribute is 0.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsSetQueueAttributes(SendQueue,
                           QUEUE_ATTRIBUTE_VISIBILITY_TIMEOUT,
                           35))
{
    printf("SqsSetQueueAttributes Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else 
{
    printf("SqsSetQueueAttributes Success\n");
}

Close Queue Handle​

The SqsCloseQueue() function is used to close queue handle opened by the SqsOpenQueue().

  • Parameter input is the SendQueue handle returned from the SqsOpenQueue() function.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.

if (!SqsCloseQueue(&SendQueue))
{
    printf("SqsCloseQueue Fails: Error Code: ");
    printf("%d\n", GetLastError());
}
else
{
    printf("SqsCloseQueue Success\n");
}



Send Feedback!