aws_iot_jobs_topics.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_job_topics.h
00018  * @brief Functions for parsing and creating MQTT topics used by the AWS IoT Jobs system.
00019  */
00020 
00021 #ifdef DISABLE_IOT_JOBS
00022 #error "Jobs API is disabled"
00023 #endif
00024 
00025 #ifndef AWS_IOT_JOBS_TOPICS_H_
00026 #define AWS_IOT_JOBS_TOPICS_H_
00027 
00028 #include <stdint.h>
00029 #include <stdbool.h>
00030 #include <stddef.h>
00031 
00032 #ifdef __cplusplus
00033 extern "C" {
00034 #endif
00035 
00036 #define JOB_ID_NEXT     "$next"
00037 #define JOB_ID_WILDCARD "+"
00038 
00039 /**
00040  * The type of job topic.
00041  */
00042 typedef enum {
00043     JOB_UNRECOGNIZED_TOPIC = 0,
00044     JOB_GET_PENDING_TOPIC,
00045     JOB_START_NEXT_TOPIC,
00046     JOB_DESCRIBE_TOPIC,
00047     JOB_UPDATE_TOPIC,
00048     JOB_NOTIFY_TOPIC,
00049     JOB_NOTIFY_NEXT_TOPIC,
00050     JOB_WILDCARD_TOPIC
00051 } AwsIotJobExecutionTopicType;
00052 
00053 /**
00054  * The type of reply topic, or #JOB_REQUEST_TYPE for
00055  * topics that are not replies.
00056  */
00057 typedef enum {
00058     JOB_UNRECOGNIZED_TOPIC_TYPE = 0,
00059     JOB_REQUEST_TYPE,
00060     JOB_ACCEPTED_REPLY_TYPE,
00061     JOB_REJECTED_REPLY_TYPE,
00062     JOB_WILDCARD_REPLY_TYPE
00063 } AwsIotJobExecutionTopicReplyType;
00064 
00065 /**
00066  * @brief Get the topic matching the provided details and put into the provided buffer.
00067  *
00068  * If the buffer is not large enough to store the full topic the topic will be truncated
00069  * to fit, with the last character always being a null terminator.
00070  *
00071  * \param buffer the buffer to put the results into
00072  * \param bufferSize the size of the buffer
00073  * \param topicType the type of the topic
00074  * \param replyType the reply type of the topic
00075  * \param thingName the name of the thing in the topic
00076  * \param jobId the name of the job id in the topic
00077  * \return the number of characters in the topic excluding the null terminator. A return
00078  *   value of bufferSize or more means that the topic string was truncated.
00079  */
00080 int aws_iot_jobs_get_api_topic(char *buffer, size_t bufferSize,
00081         AwsIotJobExecutionTopicType topicType, AwsIotJobExecutionTopicReplyType replyType,
00082         const char* thingName, const char* jobId);
00083 
00084 #ifdef __cplusplus
00085 }
00086 #endif
00087 
00088 #endif /* AWS_IOT_JOBS_TOPICS_H_ */