How to use Cloud SNS Library

Attention: 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 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());
}