Shadow_MatchTopicString

Given the topic string of an incoming message, determine whether it is related to a device shadow; if it is, return information about the type of device shadow message, and pointers to the Thing Name and Shadow Name inside of the topic string. See ShadowMessageType_t for the list of message types. Those types correspond to Device Shadow Topics.

ShadowStatus_t Shadow_MatchTopicString( const char * pTopic,
                                        uint16_t topicLength,
                                        ShadowMessageType_t * pMessageType,
                                        const char ** pThingName,
                                        uint8_t * pThingNameLength,
                                        const char ** pShadowName,
                                        uint8_t * pShadowNameLength );

Note

When this function returns, the pointer pThingName points at the first character of the <thingName> segment inside of the topic string. Likewise, the pointer pShadowName points at the first character of the <shadowName> segment inside of the topic string (if the topic is for a named shadow, not the "Classic" shadow.) Caller is responsible for keeping the memory holding the topic string around while accessing the Thing Name through pThingName and the Shadow Name through pShadowName.

Parameters

[in]	pTopic	Pointer to the MQTT topic string. Does not have to be null-terminated.
[in]	topicLength	Length of the MQTT topic string.
[out]	pMessageType	Pointer to caller-supplied memory for returning the type of the shadow message.
[out]	pThingName	Points to the 1st character of Thing Name inside of the topic string, and can be null if caller does not need to know the Thing Name contained in the topic string.
[out]	pThingNameLength	Pointer to caller-supplied memory for returning the length of the Thing Name, and can be null if caller does not need to know the Thing Name contained in the topic string.
[out]	pShadowName	Points to the 1st character of Shadow Name inside of the topic string, and can be null if caller does not need to know the Shadow Name contained in the topic string. Null is returned if the shadow is Classic.
[out]	pShadowNameLength	Pointer to caller-supplied memory for returning the length of the Shadow Name, and can be null if caller does not need to know the Shadow Name contained in the topic string. A value of 0 is returned if the shadow is Classic.

Returns

One of the following:

• SHADOW_SUCCESS if the message is related to a device shadow;
• An error code defined in ShadowStatus_t if the message is not related to a device shadow, if any input parameter is invalid, or if the function fails to parse the topic string.

Example

// Variables used in this example.
 
#define SHADOW_TOPIC_MAX_LENGTH  ( 256U )
 
ShadowStatus_te shadowStatus = SHADOW_SUCCESS;
char * pTopicName; //usually supplied by MQTT stack
uint16_t topicNameLength; //usually supplied by MQTT stack
ShadowMessageType_t messageType;
 
shadowStatus = Shadow_MatchTopicString( pTopicName,
                                        topicNameLength,
                                        &messageType,
                                        NULL,
                                        NULL,
                                        NULL,
                                        NULL );
 
if( shadowStatus == SHADOW_SUCCESS )
{
     // It is a device shadow message. And the type of the message has been returned in messageType.
     // Now we can act on the message.
}