aws_iot_jobs_interface.h

00001 /*
00002  * Copyright 2015-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License").
00005  * You may not use this file except in compliance with the License.
00006  * A copy of the License is located at
00007  *
00008  * http://aws.amazon.com/apache2.0
00009  *
00010  * or in the "license" file accompanying this file. This file is distributed
00011  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
00012  * express or implied. See the License for the specific language governing
00013  * permissions and limitations under the License.
00014  */
00015 
00016 /**
00017  * @file aws_iot_jobs_interface.h
00018  * @brief An interface for interacting with the AWS IoT Jobs system.
00019  *
00020  * This file defines utility functions for interacting with the AWS IoT jobs
00021  * APIs over MQTT. It provides functions for managing subscriptions to job
00022  * related topics and for sending queries and updates requests for jobs.
00023  * Callers are responsible for managing the subscriptions and associating
00024  * responses with the queries and update messages.
00025  */
00026 #ifndef AWS_IOT_JOBS_INTERFACE_H_
00027 #define AWS_IOT_JOBS_INTERFACE_H_
00028 
00029 #ifdef DISABLE_IOT_JOBS
00030 #error "Jobs API is disabled"
00031 #endif
00032 
00033 /**
00034  * @file aws_iot_jobs_interface.h
00035  * @brief Functions for interacting with the AWS IoT Jobs system.
00036  */
00037 #include "aws_iot_mqtt_client_interface.h"
00038 #include "aws_iot_jobs_topics.h"
00039 #include "aws_iot_jobs_types.h"
00040 #include "aws_iot_error.h"
00041 #include "aws_iot_json_utils.h"
00042 
00043 #ifdef __cplusplus
00044 extern "C" {
00045 #endif
00046 
00047 /**
00048  * @brief Subscribe to jobs messages for the given thing and/or jobs.
00049  *
00050  * The function can be used to subscribe to all job related messages. To subscribe
00051  * to messages not related to a job the jobId passed should be null. The jobId
00052  * can also be "+" to subscribe to messages related to any job, or "$next" to
00053  * indicate the next pending job.
00054  *
00055  * See also #aws_iot_jobs_subscribe_to_all_job_messages to subscribe to all possible
00056  * messages in one operation.
00057  *
00058  * \note Subscribing with the same thing, job and topic type more than
00059  *   once is undefined.
00060  *
00061  * \param pClient the client to use
00062  * \param qos the qos to use
00063  * \param thingName the name of the thing to subscribe to
00064  * \param jobId the job id to subscribe to. To subscribe to messages not related to 
00065  *   a job the jobId passed should be null. The jobId can also be "+" to subscribe to 
00066  *   messages related to any job, or "$next" to indicate the next pending job.
00067  * \param topicType the topic type to subscribe to
00068  * \param replyType the reply topic type to subscribe to
00069  * \param pApplicationHandler the callback handler
00070  * \param pApplicationHandlerData the callback context data. This must remain valid at least until
00071  *   aws_iot_jobs_unsubscribe_from_job_messages is called.
00072  * \param topicBuffer. A buffer to use to hold the topic name for the subscription. This buffer
00073  *   must remain valid at least until aws_iot_jobs_unsubscribe_from_job_messages is called.
00074  * \param topicBufferSize the size of the topic buffer. The function will fail
00075  *   with LIMIT_EXCEEDED_ERROR if this is too small.
00076  * \return the result of subscribing to the topic (see aws_iot_mqtt_subscribe)
00077  */
00078 IoT_Error_t aws_iot_jobs_subscribe_to_job_messages(
00079         AWS_IoT_Client *pClient, QoS qos,
00080         const char *thingName,
00081         const char *jobId,
00082         AwsIotJobExecutionTopicType topicType,
00083         AwsIotJobExecutionTopicReplyType replyType,
00084         pApplicationHandler_t pApplicationHandler,
00085         void *pApplicationHandlerData,
00086         char *topicBuffer,
00087         uint16_t topicBufferSize);
00088 
00089 /**
00090  * @brief Subscribe to all job messages.
00091  *
00092  * Subscribe to all job messages for the given thing.
00093  *
00094  * \note Subscribing with the same thing more than once is undefined.
00095  *
00096  * \param pClient the client to use
00097  * \param qos the qos to use
00098  * \param thingName the name of the thing to subscribe to
00099  * \param pApplicationHandler the callback handler
00100  * \param pApplicationHandlerData the callback context data. This must remain valid at least until
00101  *   aws_iot_jobs_unsubscribe_from_job_messages is called.
00102  * \param topicBuffer. A buffer to use to hold the topic name for the subscription. This buffer
00103  *   must remain valid at least until aws_iot_jobs_unsubscribe_from_job_messages is called.
00104  * \param topicBufferSize the size of the topic buffer. The function will fail
00105  *   with LIMIT_EXCEEDED_ERROR if this is too small.
00106  * \return the result of subscribing to the topic (see aws_iot_mqtt_subscribe)
00107  */
00108 IoT_Error_t aws_iot_jobs_subscribe_to_all_job_messages(
00109         AWS_IoT_Client *pClient, QoS qos,
00110         const char *thingName,
00111         pApplicationHandler_t pApplicationHandler,
00112         void *pApplicationHandlerData,
00113         char *topicBuffer,
00114         uint16_t topicBufferSize);
00115 
00116 /**
00117  * @brief Unsubscribe from a job subscription
00118  *
00119  * Remove the subscription created using #aws_iot_jobs_subscribe_to_job_messages or
00120  *   #aws_iot_jobs_subscribe_to_all_job_messages.
00121  *
00122  * \param pClient the client to use
00123  * \param topicBuffer the topic buffer passed to #aws_iot_jobs_subscribe_to_job_messages or 
00124  *   #aws_iot_jobs_subscribe_to_all_job_messages when the subscription was created.
00125  * \return #AWS_SUCCESS or the first error encountered.
00126  */
00127 IoT_Error_t aws_iot_jobs_unsubscribe_from_job_messages(
00128         AWS_IoT_Client *pClient,
00129         char *topicBuffer);
00130 
00131 /**
00132  * @brief Send a query to one of the job query APIs.
00133  *
00134  * Send a query to one of the job query APIs. If jobId is null this
00135  * requests a list of pending jobs for the thing. If jobId is
00136  * not null then it sends a query for the details of that job.
00137  * If jobId is $next then it sends a query for the details for
00138  * the next pending job.
00139  *
00140  * \param pClient the client to use
00141  * \param qos the qos to use
00142  * \param thingName the thing name to query for
00143  * \param jobId the id of the job to query for. If null a list
00144  *   of all pending jobs for the thing is requested.
00145  * \param clientToken the client token to use for the query.
00146  *   If null no clientToken is sent resulting in an empty message.
00147  * \param topicBuffer the topic buffer to use. This may be discarded
00148  *   as soon as this function returns
00149  * \param topicBufferSize the size of topicBuffer
00150  * \param messageBuffer the message buffer to use. May be NULL
00151  *   if clientToken is NULL
00152  * \param messageBufferSize the size of messageBuffer
00153  * \param topicType the topic type to publish query to
00154  * \return LIMIT_EXCEEDED_ERROR if the topic buffer or
00155  *   message buffer is too small, NULL_VALUE_ERROR if the any of
00156  *   the required inputs are NULL, otherwise the result
00157  *   of the mqtt publish
00158  */
00159 IoT_Error_t aws_iot_jobs_send_query(
00160         AWS_IoT_Client *pClient, QoS qos,
00161         const char *thingName,
00162         const char *jobId,
00163         const char *clientToken,
00164         char *topicBuffer,
00165         uint16_t topicBufferSize,
00166         char *messageBuffer,
00167         size_t messageBufferSize,
00168         AwsIotJobExecutionTopicType topicType);
00169 
00170 /**
00171  * @brief Send a start next command to the job start-next API.
00172  *
00173  * Send a start next command to the job start-next API.
00174  *
00175  * \param pClient the client to use
00176  * \param qos the qos to use
00177  * \param thingName the thing name to query for
00178  * \param startNextRequest the start-next request to send
00179  * \param topicBuffer the topic buffer to use. This may be discarded
00180  *   as soon as this function returns
00181  * \param topicBufferSize the size of topicBuffer
00182  * \param messageBuffer the message buffer to use. May be NULL
00183  *   if clientToken is NULL
00184  * \param messageBufferSize the size of messageBuffer
00185  * \return LIMIT_EXCEEDED_ERROR if the topic buffer or
00186  *   message buffer is too small, NULL_VALUE_ERROR if the any of
00187  *   the required inputs are NULL, otherwise the result
00188  *   of the mqtt publish
00189  */
00190 IoT_Error_t aws_iot_jobs_start_next(
00191         AWS_IoT_Client *pClient, QoS qos,
00192         const char *thingName,
00193         const AwsIotStartNextPendingJobExecutionRequest *startNextRequest,
00194         char *topicBuffer,
00195         uint16_t topicBufferSize,
00196         char *messageBuffer,
00197         size_t messageBufferSize);
00198 
00199 /**
00200  * @brief Send a describe job query to the job query API.
00201  *
00202  * Send a describe job query to the job query API. If jobId is null this
00203  * requests a list of pending jobs for the thing. If jobId is
00204  * not null then it sends a query for the details of that job.
00205  *
00206  * \param pClient the client to use
00207  * \param qos the qos to use
00208  * \param thingName the thing name to query for
00209  * \param jobId the id of the job to query for. If null a list
00210  *   of all pending jobs for the thing is requested.
00211  * \param describeRequest the describe request to send
00212  * \param topicBuffer the topic buffer to use. This may be discarded
00213  *   as soon as this function returns
00214  * \param topicBufferSize the size of topicBuffer
00215  * \param messageBuffer the message buffer to use. May be NULL
00216  *   if clientToken is NULL
00217  * \param messageBufferSize the size of messageBuffer
00218  * \return LIMIT_EXCEEDED_ERROR if the topic buffer or
00219  *   message buffer is too small, NULL_VALUE_ERROR if the any of
00220  *   the required inputs are NULL, otherwise the result
00221  *   of the mqtt publish
00222  */
00223 IoT_Error_t aws_iot_jobs_describe(
00224         AWS_IoT_Client *pClient, QoS qos,
00225         const char *thingName,
00226         const char *jobId,
00227         const AwsIotDescribeJobExecutionRequest *describeRequest,
00228         char *topicBuffer,
00229         uint16_t topicBufferSize,
00230         char *messageBuffer,
00231         size_t messageBufferSize);
00232 
00233 /**
00234  * @brief Send an update about a job execution.
00235  *
00236  * Send an update about a job execution.
00237  *
00238  * \param pClient the client to use
00239  * \param qos the qos to use
00240  * \param thingName the thing name to send the update for
00241  * \param jobId the id of the job to send the update for
00242  * \param updateRequest the update request to send
00243  * \param topicBuffer the topic buffer to use. This may be discarded
00244  *   as soon as this function returns
00245  * \param topicBufferSize the size of topicBuffer
00246  * \param messageBuffer the message buffer to use.
00247  * \param messageBufferSize the size of messageBuffer
00248  * \return LIMIT_EXCEEDED_ERROR if the topic buffer or
00249  *   message buffer is too small, NULL_VALUE_ERROR if the any of
00250  *   the required inputs are NULL, otherwise the result
00251  *   of the mqtt publish
00252  */
00253 IoT_Error_t aws_iot_jobs_send_update(
00254         AWS_IoT_Client *pClient, QoS qos,
00255         const char *thingName,
00256         const char *jobId,
00257         const AwsIotJobExecutionUpdateRequest *updateRequest,
00258         char *topicBuffer,
00259         uint16_t topicBufferSize,
00260         char *messageBuffer,
00261         size_t messageBufferSize);
00262 
00263 #ifdef __cplusplus
00264 }
00265 #endif
00266 
00267 #endif /* AWS_IOT_JOBS_INTERFACE_H_ */