coap API: Add Set Content Format API call. (#1889)

* coap API: Add Append Content Format API call.

This allows us to easily set the content format of outgoing messages by
wrapping otCoapHeaderAppendUintOption.  Additionally, some standard CoAP
content format codes are defined as an enum.

[Supercedes commit 52cddd3a4f4127dc22e64b65fd9392dc09aa79d8]

* coap header: Re-work AppendContentFormatOption

Remove the practically empty `MediaType` enum and replace it with the
more complete (but more verbose) `otCoapOptionContentFormat` so that it
is consistent with other CoAP API functions.

* coap header: Use C++ static cast

As per review notes (pull request #1889).

* coap api: Add blank line between @param and @retval

As per review comments (pull request #1889).

include/openthread/coap.h

@@ -148,6 +148,20 @@ typedef struct otCoapOption
     const uint8_t *mValue;   ///< A pointer to the Option Value
 } otCoapOption;
 
+/**
+ * CoAP Content Format codes.  The full list is documented at
+ * https://tools.ietf.org/html/rfc7252#page-92
+ */
+typedef enum otCoapOptionContentFormat
+{
+    OT_COAP_OPTION_CONTENT_FORMAT_TEXT_PLAIN    = 0,    ///< text/plain
+    OT_COAP_OPTION_CONTENT_FORMAT_LINK_FORMAT   = 40,   ///< application/link-format
+    OT_COAP_OPTION_CONTENT_FORMAT_XML           = 41,   ///< application/xml
+    OT_COAP_OPTION_CONTENT_FORMAT_OCTET_STREAM  = 42,   ///< application/octet-stream
+    OT_COAP_OPTION_CONTENT_FORMAT_EXI           = 47,   ///< application/exi
+    OT_COAP_OPTION_CONTENT_FORMAT_JSON          = 50,   ///< application/json
+} otCoapOptionContentFormat;
+
 #define OT_COAP_HEADER_MAX_LENGTH       128  ///< Max CoAP header length (bytes)
 
 /**
@@ -244,6 +258,26 @@ void otCoapHeaderSetToken(otCoapHeader *aHeader, const uint8_t *aToken, uint8_t
  */
 void otCoapHeaderGenerateToken(otCoapHeader *aHeader, uint8_t aTokenLength);
 
+/**
+ * This function appends the Content Format CoAP option as specified in
+ * https://tools.ietf.org/html/rfc7252#page-92.  This *must* be called before
+ * setting otCoapHeaderSetPayloadMarker if a payload is to be included in the
+ * message.
+ *
+ * The function is a convenience wrapper around otCoapHeaderAppendUintOption,
+ * and if the desired format type code isn't listed in otCoapOptionContentFormat,
+ * this base function should be used instead.
+ *
+ * @param[inout]  aHeader           A pointer to the CoAP header.
+ * @param[in]     aContentFormat    One of the content formats listed in
+ *                                  otCoapOptionContentFormat above.
+ *
+ * @retval OT_ERROR_NONE          Successfully appended the option.
+ * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
+ * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
+ */
+otError otCoapHeaderAppendContentFormatOption(otCoapHeader *aHeader, otCoapOptionContentFormat aContentFormat);
+
 /**
  * This function appends a CoAP option in a header.
  *

src/core/api/coap_api.cpp

@@ -58,6 +58,11 @@ void otCoapHeaderGenerateToken(otCoapHeader *aHeader, uint8_t aTokenLength)
     static_cast<Coap::Header *>(aHeader)->SetToken(aTokenLength);
 }
 
+otError otCoapHeaderAppendContentFormatOption(otCoapHeader *aHeader, otCoapOptionContentFormat aContentFormat)
+{
+    return static_cast<Coap::Header *>(aHeader)->AppendContentFormatOption(aContentFormat);
+}
+
 otError otCoapHeaderAppendOption(otCoapHeader *aHeader, const otCoapOption *aOption)
 {
     return static_cast<Coap::Header *>(aHeader)->AppendOption(*static_cast<const Coap::Header::Option *>(aOption));

src/core/coap/coap_header.cpp

@@ -313,9 +313,9 @@ exit:
     return error;
 }
 
-otError Header::AppendContentFormatOption(MediaType aType)
+otError Header::AppendContentFormatOption(otCoapOptionContentFormat aContentFormat)
 {
-    return AppendUintOption(OT_COAP_OPTION_CONTENT_FORMAT, aType);
+    return AppendUintOption(OT_COAP_OPTION_CONTENT_FORMAT, static_cast<uint32_t>(aContentFormat));
 }
 
 otError Header::AppendMaxAgeOption(uint32_t aMaxAge)

src/core/coap/coap_header.hpp

@@ -310,26 +310,17 @@ public:
      */
     otError AppendUriPathOptions(const char *aUriPath);
 
-    /**
-     * Media Types
-     *
-     */
-    enum MediaType
-    {
-        kApplicationOctetStream = 42,  ///< application/octet-stream
-    };
-
     /**
      * This method appends a Content-Format option.
      *
-     * @param[in]  aType  The Media Type value.
+     * @param[in]  aContentFormat  The Content Format value.
      *
      * @retval OT_ERROR_NONE          Successfully appended the option.
      * @retval OT_ERROR_INVALID_ARGS  The option type is not equal or greater than the last option type.
      * @retval OT_ERROR_NO_BUFS       The option length exceeds the buffer size.
      *
      */
-    otError AppendContentFormatOption(MediaType aType);
+    otError AppendContentFormatOption(otCoapOptionContentFormat aContentFormat);
 
     /**
      * This method appends a Max-Age option.