Search by Tags

How to use Cloud SNS Library

 

Compare with Revision




Subscribe for this article updates

Amazon Simple Notification Service (Amazon SNS)

Amazon Simple Notification Service (Amazon SNS) is a web service that makes it easy to set up, operate, and send notifications from the cloud. It provides developers with a highly scalable, flexible, and cost-effective capability to publish messages from an application and immediately deliver them to subscribers or other applications. It is designed to make web-scale computing easier for developers.

Notes:

  • The number of Topics is limited to 100 per region.
  • Use a small length Topic Name for a fast response time.
  • Use only alphanumeric/underscore/hyphen characters to construct the Topic Name and Display Name. 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.

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

Open SNS Handle

Before calling any other function, call SnsOpenTopic() with all the parameter inputs: AWS Access Id, AWS Secret Key, AWS Owner ID, AWS SnS Region / Path,topicName, Topic and Display name(optional).

  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
HSNS NewTopic; //Declare Topic handle
 
if (!SnsOpenTopic(AWS_ACCOUNT_ACCESS_ID,
                  AWS_ACCOUNT_SECRET_KEY,
                  AWS_ACCOUNT_OWNER_ID,
                  AWS_SQS_USA_EAST_REGION,
                  “TopicName”,
                  “DisplayName”,
                  &NewTopic))
{
    printf("SnsOpenTopic Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsOpenTopic Success\n");
}

NewTopic needs to be passed to all function calls after this point.

Create New Topic

The SnsCreateTopic() function is used to create a new topic. This is the 2nd function to be called after SnsOpenTopic(). It is mandatory to call this function otherwise other calls will automatically fail.

  • The 1st parameter is the NewTopic handle returned from SnsOpenTopic() function call.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsCreateTopic(NewTopic))
{
    printf("SnsCreateTopic Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsCreateTopic Success\n");
}

List All the Topics in a Region

SnsListTopics() function is used to list all the topics.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the path of the local file in which the list 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 (!SnsListTopics(NewTopic, "\\listoftopics.txt"))
{
    printf("SnsListTopics Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsListTopics Success\n");
}

Find a Topic from List Stored in a Local File

The SnsFindTopic() function is used to find topic details one by one from a list data stored in the local file.

  • 1st parameter is the path of the local file in which list data needs be stored.
  • 2nd parameter is the pointer to the memory in which the function will put the data.
  • 3rd parameter is the size of the memory allocated for the 2nd parameter.
  • 4th parameter is the pointer to a memory location in which the function will put the location for the next topic detail. To find the 1st topic from the list put this variable as zero.
  • 5th parameter is the size of the local file.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
DWORD listTopicNextPointer = 0;
char topicData[256] = {0};
 
memset(topicData, 0, 256);
if (SnsFindTopic("\\listoftopics.txt",
                 topicData,
                 BUFFER_SIZE_TOPIC_DATA,
                 &listTopicNextPointer,
                 fileSize))   
{
    printf("> %s\n", topicData);
}

To find the next topic, call SnsFindTopic again as below. This time don’t set listTopicNextPointer to zero.

memset(topicData, 0, 256);
if (SnsFindTopic("\\listoftopics.txt",
                 topicData,
                 BUFFER_SIZE_TOPIC_DATA,
                 &listTopicNextPointer,
                 fileSize))   
{
    printf("> %s\n", topicData);
}

Delete a Topic

The SnsDeleteTopic() function is used to delete a topic.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsDeleteTopic(NewTopic))
{
    printf("SnsDeleteTopic Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsDeleteTopic Success\n");
}

List All the Subscriptions of a Topic in a Region

The SnsListSubscriptions() function is used to list all the subscriptions of a topic.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the path of the local file in which the list data needs be stored.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsListSubscriptions(NewTopic, "\\ListSubscriptionsByTopic.txt"))
{
    printf("SnsListSubscriptions Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else
{
    printf("SnsListSubscriptions Success\n");
}

Find a Subscription from List Stored in a Local File

The SnsFindSubscriptions() function is used to find subscription details one by one from list data stored in the local file.

  • 1st parameter is the path of the local file in which the list data needs be stored.
  • 2nd parameter is the pointer to the memory in which the function will put the data.
  • 3rd parameter is the size of the memory allocated for the 2nd parameter.
  • 4th parameter is the pointer to a memory location in which the function will put the location for the next topic detail. To find the 1st subscription from the list, put this variable as zero.
  • 5th parameter is the size of the local file.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
DWORD listSubscriptionNextPointer = 0;
char subscriptionData[1024] = {0};
 
memset(subscriptionData, 0, 1024);
if (SnsFindSubscriptions("\\ListSubscriptionsByTopic.txt",
                         subscriptionData,
                         1024,
                         &listSubscriptionNextPointer,
                         fileSize))
{ 
printf("> %s\n", subscriptionData);
}

To find the next subscription call SnsFindSubscriptions() again as detailed below. This time don’t set listSubscriptionNextPointer to zero.

memset(subscriptionData, 0, 1024);
if (SnsFindSubscriptions("\\ListSubscriptionsByTopic.txt",
                         subscriptionData,
                         1024,
                         &listSubscriptionNextPointer,
                         fileSize))
{ 
printf("> %s\n", subscriptionData);
}

Subscribe an Endpoint to a Topic

The SnsSubscribe() function is used to subscribe an endpoint to a topic.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the endpoint. For email endpoint: example@toradex.com. For SMS it should be the phone number with country code.
  • 3rd parameter is the protocol type. For more details please check API documentation at: http://developer.toradex.com/knowledge-base/cloud-sns-lib-api#ac8c11fccf90d19565c1b8d2843df47db
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
// USE MACRO for 3rd parameter
if (!SnsSubscribe(NewTopic, “example@toradex.com”, PROTOCOL_TYPE_EMAIL))
{
    printf("SnsSubscribe Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsSubscribe Success\n");
}

Unsubscribe a Subscription From a Topic

The SnsUnsubscribe() function is used to unsubscribe an endpoint from a topic.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the subscription ARN., You can use SnsFindSubscriptions() to get subscription ARN (Amazon Resource Name).
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsUnsubscribe(NewTopic, "arn:aws:sns:us-east-1:823890622362:USA_NewAlerts-1:e86e12f4-ccb7-4153-acd2-33a2c8e30de5"))
{
    printf("SnsUnsubscribe Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsUnsubscribe Success\n");
}

Get Subscription Attributes

The SnsGetSubscriptionAttribtues() function is used to get subscription attributes.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the subscription ARN, you can use the SnsFindSubscriptions() to get the subscription ARN (Amazon Resource Name).
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
char subscriptionAttributesData[1024] = {0};
memset(subscriptionAttributesData, 0, 1024);
if (!SnsGetSubscriptionAttribtues(NewTopic, "arn:aws:sns:us-east-1:823890622362:test:81bb4313-b150-48bf-8fd5-cf98a6a85535", subscriptionAttributesData, 1024))
{
    printf("SnsGetSubscriptionAttribtues Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("%s\n", subscriptionAttributesData);
    printf("SnsGetSubscriptionAttribtues Success\n");
}

Get Topic Attributes

The SnsGetTopicAttributes() function is used to get topic attributes.

  • 1st parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the pointer to the memory in which the attribute data will be returned by the function if successful.
  • 3rd parameter is the size of the memory allocated for the 2nd parameter.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
char  topicAttributesData[1024] = {0};
memset(topicAttributesData, 0, 1024);
if (!SnsGetTopicAttributes(NewTopic, topicAttributesData, 1024))
{
    printf("SnsGetTopicAttributes Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("%s\n", topicAttributesData);
    printf("SnsGetTopicAttributes Success\n");
}

Sets a Topic Attribute

The SnsSetTopicAttributes() function is used to set the attribute of a topic.

  • 1st Parameter is the NewTopic handle returned from SnsOpenTopic() function call.
  • 2nd parameter is the attribute type use macros:
#define ATTRIBUTE_TYPE_POLICY             1 
#define ATTRIBUTE_TYPE_DISPLAYNAME        2 
#define ATTRIBUTE_TYPE_DELIVERYPOLICY     3 
  • 3rd parameter is the attribute name/value.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsSetTopicAttributes(NewTopic, ATTRIBUTE_TYPE_DISPLAYNAME, “TORADEX”))
{
    printf("SnsSetTopicAttributes Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsSetTopicAttributes Success\n");
}

Publish a Message to a Topic

The SnsPublish() function is used to send a message to a topic.

  • 1st Parameter is the NewTopic handle returned from the SnsOpenTopic() function call.
  • 2nd parameter is the Subject (optional - only intended for email endpoints).
  • 3rd parameter is the Message to be sent.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsPublish(NewTopic, 
                "Test", 
                "Message, sent by Toradex SNS Cloud Library :)"))
{
    printf("SnsPublish Fail");
    printf(", Error Code: %d\n", GetLastError());
}
else 
{
    printf("SnsPublish Success\n");
}

Close Topic

The SnsCloseTopic() function is used to close the handle opened by the call to SnsOpenTopic().

  • Parameter input is the NewTopic handle returned from the SnsOpenTopic() function call.
  • It will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
if (!SnsCloseTopic(&NewTopic))
{
    printf("SnsCloseTopic Fail");
    printf(", Error Code: %d\n", GetLastError());
}