Shadow_AssembleTopicString

Assemble shadow topic string when Thing Name or Shadow Name is only known at run time. If both the Thing Name and Shadow Name are known at compile time, use SHADOW_TOPIC_STR_* macros instead.

ShadowStatus_t Shadow_AssembleTopicString( ShadowTopicStringType_t topicType,
                                           const char * pThingName,
                                           uint8_t thingNameLength,
                                           const char * pShadowName,
                                           uint8_t shadowNameLength,
                                           char * pTopicBuffer,
                                           uint16_t bufferSize,
                                           uint16_t * pOutLength );

Parameters

[in]	topicType	Indicates what topic will be written into the buffer pointed to by pTopicBuffer. can be one of: ShadowTopicStringTypeGet ShadowTopicStringTypeGetAccepted ShadowTopicStringTypeGetRejected ShadowTopicStringTypeDelete ShadowTopicStringTypeDeleteAccepted ShadowTopicStringTypeDeleteRejected ShadowTopicStringTypeUpdate ShadowTopicStringTypeUpdateAccepted ShadowTopicStringTypeUpdateRejected ShadowTopicStringTypeUpdateDocuments ShadowTopicStringTypeUpdateDelta
[in]	pThingName	Thing Name string. No need to be null terminated. Must not be NULL.
[in]	thingNameLength	Length of Thing Name string pointed to by pThingName. Must not be zero.
[in]	pShadowName	Shadow Name string. No need to be null terminated. Must not be NULL. Empty string for classic shadow.
[in]	shadowNameLength	Length of Shadow Name string pointed to by pShadowName. Zero for classic shadow.
[out]	pTopicBuffer	Pointer to buffer for returning the topic string. Caller is responsible for supplying memory pointed to by pTopicBuffer. This function does not fill in the terminating null character. The app can supply a buffer that does not have space for holding the null character.
[in]	bufferSize	Length of pTopicBuffer. This function will return error if bufferSize is less than the length of the assembled topic string.
[out]	pOutLength	Pointer to caller-supplied memory for returning the length of the topic string.

Returns

One of the following:

• SHADOW_SUCCESS if successful.
• An error code if failed to assemble.

Example

// Variables used in this example.
 
#define SHADOW_TOPIC_MAX_LENGTH  ( 256U )
 
ShadowStatus_t shadowStatus = SHADOW_SUCCESS;
char topicBuffer[ SHADOW_TOPIC_MAX_LENGTH ] = { 0 };
uint16_t bufferSize = SHADOW_TOPIC_MAX_LENGTH;
uint16_t outLength = 0;
const char thingName[] = "TestThingName";
uint16_t thingNameLength  = ( sizeof( thingName ) - 1U );
const char shadowName[] = "TestShadowName";
uint16_t shadowNameLength  = ( sizeof( shadowName ) - 1U );
 
shadowStatus = Shadow_AssembleTopicString( ShadowTopicStringTypeUpdateDelta,
                                           thingName,
                                           thingNameLength,
                                           shadowName,
                                           shadowNameLength,
                                           & ( topicBuffer[ 0 ] ),
                                           bufferSize,
                                           & outLength );
 
if( shadowStatus == SHADOW_SUCCESS )
{
     // The assembled topic string is put in pTopicBuffer with the length outLength.
}