|
| 1 | +# Migration guide for Jobs-for-AWS-IoT-embedded-sdk version $\geq$ v2.0.0 |
| 2 | + |
| 3 | +With Jobs-for-AWS-IoT-embedded-sdk versions $\geq$ v2.0.0, there are some breaking changes that need to be addressed when upgrading. |
| 4 | + |
| 5 | +## Breaking Changes |
| 6 | + |
| 7 | +The signature of the `Jobs_UpdateMsg` API has been changed from |
| 8 | +```c |
| 9 | +size_t Jobs_UpdateMsg( JobCurrentStatus_t status, |
| 10 | + const char * expectedVersion, |
| 11 | + size_t expectedVersionLength, |
| 12 | + char * buffer, |
| 13 | + size_t bufferSize ) |
| 14 | +``` |
| 15 | +to |
| 16 | +```c |
| 17 | +size_t Jobs_UpdateMsg( JobsUpdateRequest_t request, |
| 18 | + char * buffer, |
| 19 | + size_t bufferSize ); |
| 20 | +``` |
| 21 | +A new structure `JobsUpdateRequest_t` has been introduced. This struct is now passed as a parameter to the API to include values like `status`, `expectedVersion` and `expectedVersionLength` which were earlier direct input to the API. All values in the struct except `status` are now optional. Following is the definition of the `JobsUpdateRequest_t` struct. |
| 22 | +```c |
| 23 | +typedef struct |
| 24 | +{ |
| 25 | + JobCurrentStatus_t status; /**< Status to update the job to. */ |
| 26 | + const char * expectedVersion; /**< Expected version, optional. */ |
| 27 | + size_t expectedVersionLength; /**< Expected version length, optional. */ |
| 28 | + const char * statusDetails; /**< JSON key-value pair, optional. */ |
| 29 | + size_t statusDetailsLength; /**< JSON key-value pair length, optional. */ |
| 30 | +} JobsUpdateRequest_t; |
| 31 | +``` |
| 32 | +### Old Code Snippet |
| 33 | +```c |
| 34 | +const char * expectedVersion = "2"; |
| 35 | +size_t expectedVersionLength = ( sizeof(expectedVersion ) - 1U ); |
| 36 | +JobCurrentStatus_t status = Succeeded; |
| 37 | +char messageBuffer[ UPDATE_JOB_MSG_LENGTH ] = {0}; |
| 38 | +size_t messageLength = 0U; |
| 39 | + |
| 40 | +messageLength = Jobs_UpdateMsg( status, |
| 41 | + expectedVersion, |
| 42 | + expectedVersionLength, |
| 43 | + messageBuffer, |
| 44 | + UPDATE_JOB_MSG_LENGTH ); |
| 45 | + |
| 46 | +if (messageLength > 0 ) |
| 47 | +{ |
| 48 | + // The message string of length, messageLength, has been |
| 49 | + // generated in the buffer, messageBuffer, for the UpdateJobExecution API |
| 50 | + // Publish this message to the topic generated by Jobs_Update using an |
| 51 | + // MQTT client of your choice. |
| 52 | +} |
| 53 | + ``` |
| 54 | +
|
| 55 | +### New Code Snippet |
| 56 | +```c |
| 57 | +const char * expectedVersion = "2"; |
| 58 | +const chat * statusDetails = "{\"key\":\"value\"}"; // This can be any user defined JSON key value pair |
| 59 | +char messageBuffer[ UPDATE_JOB_MSG_LENGTH ] = {0}; |
| 60 | +size_t messageLength = 0U; |
| 61 | +
|
| 62 | +JobsUpdateRequest_t request; |
| 63 | +request.status = Succeeded; |
| 64 | +request.expectedVersion = expectedVersion; |
| 65 | +request.expectedVersionLength = ( sizeof( expectedVersion ) - 1U ); |
| 66 | +request.statusDetails = statusDetails; |
| 67 | +request.statusDetailsLength = ( sizeof( statusDetails ) - 1U ); |
| 68 | +
|
| 69 | +messageLength = Jobs_UpdateMsg( request |
| 70 | + messageBuffer, |
| 71 | + UPDATE_JOB_MSG_LENGTH ); |
| 72 | +
|
| 73 | +if (messageBufferLength > 0 ) |
| 74 | +{ |
| 75 | + // The message string of length, messageLength, has been |
| 76 | + // generated in the buffer, messageBuffer, for the UpdateJobExecution API |
| 77 | + // Publish this message to the topic generated by Jobs_Update using an |
| 78 | + // MQTT client of your choice. |
| 79 | + } |
| 80 | +``` |
0 commit comments