XDK API  3.6.0
Documentation
Data Structures | Macros | Typedefs | Enumerations | Functions
Serval_Rest.h File Reference

Interface to REST constants and methodsThis module provides declarations which are commonly used by REST. This also provides the common interfaces provided by REST module e.g. interfaces to parse a REST message. More...

#include <Serval_Defines.h>
#include <Serval_Types.h>
#include <Serval_Http.h>
#include <Serval_Coap.h>
#include <Serval_Msg.h>
+ Include dependency graph for Serval_Rest.h:
+ This graph shows which files directly or indirectly include this file:

Data Structures

struct  RestParser_S
 
struct  RestSerializer_S
 

Macros

#define REST_HTTP_PAYLOAD_MAX_LEN   48
 
#define REST_MAX_URI_LEN   128
 
#define SERVAL_ENABLE_REST_SERVER_OBSERVATION   0
 

Typedefs

typedef enum Rest_Code_E Rest_Code_T
 
typedef enum Rest_ContentFormat_E Rest_ContentFormat_T
 
typedef enum Rest_Method_E Rest_Method_T
 
typedef struct RestMsg_S RestMsg_T
 
typedef struct RestParser_S RestParser_T
 
typedef uint8_t RestPayloadLength_t
 
typedef struct RestSerializer_S RestSerializer_T
 
typedef void RestSession_T
 

Enumerations

enum  Rest_Code_E
 
enum  Rest_ContentFormat_E
 
enum  Rest_Method_E
 
enum  Rest_Protocol_T
 
enum  RestSerializeType_T
 

Functions

RestMsg_TMsg_getRestMsg (Msg_T *msg_ptr)
 
Rest_Protocol_T RestMsg_getProtocol (RestMsg_T *restMsg_ptr)
 
void RestMsg_setAppCallback (Msg_T *msg_ptr, AppCallback_T appCallback)
 
retcode_t RestParser_getAccept (RestParser_T *parser_ptr, Rest_ContentFormat_T *formatBuffer_ptr, uint8_t formatBufferLen, uint8_t *numFormats_ptr)
 
retcode_t RestParser_getCode (RestParser_T *parser_ptr, Rest_Code_T *code_ptr)
 
retcode_t RestParser_getContentFormat (RestParser_T *parser_ptr, Rest_ContentFormat_T *format_ptr)
 
retcode_t RestParser_getLocationPath (RestParser_T *parser_ptr, char *buffer_ptr, uint8_t bufferLen)
 
retcode_t RestParser_getLocationQuery (RestParser_T *parser_ptr, char *buffer_ptr, uint8_t bufferLen)
 
retcode_t RestParser_getMethod (RestParser_T *parser_ptr, Rest_Method_T *method_ptr)
 
void RestParser_getPayload (RestParser_T *parser_ptr, uint8_t const **payload_pptr, RestPayloadLength_t *payloadLen_ptr)
 
retcode_t RestParser_getRange (RestParser_T *parser_ptr, uint32_t *offset, bool *complete)
 
retcode_t RestParser_getUriPath (RestParser_T *parser_ptr, char *buffer_ptr, uint8_t bufferLen)
 
retcode_t RestParser_getUriQuery (RestParser_T *parser_ptr, char *buffer_ptr, uint8_t bufferLen)
 
void RestParser_setup (RestParser_T *parser_ptr, Msg_T *msg_ptr)
 

Macro Definition Documentation

#define REST_HTTP_PAYLOAD_MAX_LEN   48

This is the length of the payload buffer of a HTTP REST message.

#define REST_MAX_URI_LEN   128

This is the length of the uri buffer used in the REST server module.

#define SERVAL_ENABLE_REST_SERVER_OBSERVATION   0

Enable ''SERVAL_ENABLE_REST_HTTP_BINDING'' in order to enable the RESTful HTTP binding code. Enable ''SERVAL_ENABLE_REST_COAP_BINDING'' in order to enable the RESTful COAP binding code. if SERVAL_ENABLE_REST => HTTP or COAP binding (or both) must be enabled if SERVAL_ENABLE_REST_HTTP_BINDING => HTTP must be enabled if REST Client and HTTP binding => HTTP Client must be enabled if REST Server and HTTP binding => HTTP Server must be enabled if SERVAL_ENABLE_REST_COAP_BINDING => COAP must be enabled if REST Client and COAP binding => COAP Client must be enabled if REST Server and COAP binding => COAP Server must be enabled Enable ''SERVAL_ENABLE_REST_OBSERVATION'' in order to enable the possiblity to observe resources of the REST server using CoAP.

Since
1.4

Typedef Documentation

typedef enum Rest_Code_E Rest_Code_T

This enum defines the response codes

This enum defines the content formats

This enum defines the request methods

typedef struct RestMsg_S RestMsg_T

The data structure for RESTful messages.

See also
struct RestMsg_S
typedef struct RestParser_S RestParser_T

This data structure represents a parsing context used during parsing of an incoming REST message.

typedef uint8_t RestPayloadLength_t

This data structure represents a serialization context used during serializing of an outgoing REST message.

typedef void RestSession_T

This data type identifies an ongoing rest communication initiated by rest client and can be used to identify and relate a fault in communication e.g. with the request sent.

Enumeration Type Documentation

This enum defines the response codes

Enumerator
REST_CREATED 
REST_DELETED 
REST_VALID 
REST_CHANGED 
REST_CONTENT 
REST_BAD_REQUEST 
REST_UNAUTHORIZED 
REST_BAD_OPTION 
REST_FORBIDDEN 
REST_NOT_FOUND 
REST_METHOD_NOT_ALLOWED 
REST_NOT_ACCEPTABLE 
REST_PRECONDITION_FAILED 
REST_REQUEST_ENTITY_TOO_LARGE 
REST_REQUEST_URI_TOO_LARGE 
REST_UNSUPPORTED_CONTENT_FORMAT 
REST_INTERNAL_SERVER_ERROR 
REST_NOT_IMPLEMENTED 
REST_BAD_GATEWAY 
REST_SERVICE_UNAVAILABLE 
REST_GATEWAY_TIMEOUT 
REST_PROXYING_NOT_SUPPORTED 

This enum defines the content formats

Enumerator
REST_CONTENT_FMT_TEXT_UTF8 
REST_CONTENT_FMT_LINK_FORMAT 
REST_CONTENT_FMT_XML 
REST_CONTENT_FMT_OCTET_STREAM 
REST_CONTENT_FMT_EXI 
REST_CONTENT_FMT_JSON 
REST_CONTENT_FMT_MAX 
REST_CONTENT_FMT_HTML 

This enum defines the request methods

Enumerator
REST_GET 
REST_POST 
REST_PUT 
REST_DELETE 

This enumeration defines the possible protocols of a REST message

Enumerator
REST_PROTOCOL_COAP 
REST_PROTOCOL_HTTP 

This enum gives the type of REST message being serialized

Enumerator
REST_RESPONSE 
REST_REQUEST 

Function Documentation

RestMsg_T* Msg_getRestMsg ( Msg_T msg_ptr)

This function provides a pointer to the structure holding REST message in the given Msg_T object.

Parameters
[in]msg_ptrReference to a Msg_T object. It has to be a valid pointer.
Returns
a pointer of type RestMsg_T to the required REST message structure.
Rest_Protocol_T RestMsg_getProtocol ( RestMsg_T restMsg_ptr)

This function returns the underlying protocol of a rest message

Parameters
[in]Therest message for which to get the protocol
Returns
The protocol type of the message
Since
1.5
void RestMsg_setAppCallback ( Msg_T msg_ptr,
AppCallback_T  appCallback 
)

This function is called to initialize application callback defined by application to inform it of some event.

Parameters
[in]msg_ptrReference to a Msg_T object which holds the current message. It has to be a valid pointer.
[in]appCallbackReference to a AppCallback_T object, this holds the application callback to be called to inform application about the success or failure of response.
Since
1.3
retcode_t RestParser_getAccept ( RestParser_T parser_ptr,
Rest_ContentFormat_T formatBuffer_ptr,
uint8_t  formatBufferLen,
uint8_t *  numFormats_ptr 
)

This function retrieves the accepted formats which are stored in the message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]formatBuffer_ptrReference to the buffer which is provided for storing the different acceptable Content Formats.
[in]formatBufferLenLength of the buffer which is provided for storing the acceptable Content Formats.
[out]numFormats_ptrReference to the uint8_t object where the extracted number of acceptable Content Formats will be stored to.
Returns
RC_OK if successful
RC_REST_BUFFER_TOO_SMALL if the number of acceptable content formats defined in the message is greater than the capacity of the given buffer RC_REST_BINDING_PARSING_ERROR if an error has occurred during the parsing
retcode_t RestParser_getCode ( RestParser_T parser_ptr,
Rest_Code_T code_ptr 
)

This function retrieves the Code of the given message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context. It has to be a valid pointer.
[out]code_ptrReference to a Rest_Code_T object were the Code of the message should be copied to.
Returns
RC_OK if successful
RC_REST_UNKNOWN_STATUS_CODE if the Code is not known.
retcode_t RestParser_getContentFormat ( RestParser_T parser_ptr,
Rest_ContentFormat_T format_ptr 
)

This function retrieves the Content Format which is stored in the message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]format_ptrReference to the Rest_ContentFormat_T which is provided for storing the value of the Content Format option.
Returns
RC_OK if successful
RC_REST_PARSER_NO_CONTENT_FORMAT if the content format is not specified RC_REST_BINDING_PARSING_ERROR if an error has occurred during the parsing RC_REST_PARSER_UNSUPPORTED_CONTENT_FORMAT in case of an HTTP message if the HTTP content type can not be mapped to a REST content format
retcode_t RestParser_getLocationPath ( RestParser_T parser_ptr,
char *  buffer_ptr,
uint8_t  bufferLen 
)

This function retrieves the Location Path as a string of an incoming message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]buffer_ptrReference to the buffer which is provided for storing the Location Path. The returned string is null terminated.
[in]bufferLenLength of the allocated buffer which is provided to store the Location Path.
Returns
RC_OK if successful
RC_REST_BUFFER_TOO_SMALL if the string is larger than the provided buffer.
retcode_t RestParser_getLocationQuery ( RestParser_T parser_ptr,
char *  buffer_ptr,
uint8_t  bufferLen 
)

This function retrieves the Location Query as a string of an incoming message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]buffer_ptrReference to the buffer which is provided for storing the Location Query. The returned string is null terminated.
[in]bufferLenLength of the allocated buffer which is provided to store the Location Query.
Returns
RC_OK if successful
RC_REST_BUFFER_TOO_SMALL if the string is larger than the provided buffer.
retcode_t RestParser_getMethod ( RestParser_T parser_ptr,
Rest_Method_T method_ptr 
)

This function retrieves the Method of the given message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context. It has to be a valid pointer.
[out]method_ptrReference to a Rest_Method_T object were the Method of the message should be copied to.
Returns
RC_OK if successful
RC_REST_PARSER_UNSUPPORTED_METHOD if the Method is not known.
void RestParser_getPayload ( RestParser_T parser_ptr,
uint8_t const **  payload_pptr,
RestPayloadLength_t payloadLen_ptr 
)

This function retrieves the payload of an incoming message. The implementation of this function will parse through all the options in case of CoAP is used.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]payload_pptrOutput parameter for the payload reference. It must be a valid pointer.
[out]payloadLen_ptrOutput paramter for the payload length. It must be a valid pointer.
retcode_t RestParser_getRange ( RestParser_T parser_ptr,
uint32_t *  offset,
bool *  complete 
)

Retrieve the offset of the range of the message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]offsetThe offset of this range.
[out]completetrue if the range is complete, false otherwise
Returns
RC_OK if successful RC_REST_BINDING_PARSING_ERROR if the range length does not match the content length RC_REST_PARSER_MESSAGE_NOT_SPLIT if the message does not contain a range
retcode_t RestParser_getUriPath ( RestParser_T parser_ptr,
char *  buffer_ptr,
uint8_t  bufferLen 
)

This function retrieves the URI Path as a string of an incoming message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]buffer_ptrReference to the buffer which is provided for storing the URI Path. The returned string is null terminated.
[in]bufferLenLength of the allocated buffer which is provided to store the URI Path.
Returns
RC_OK if successful
RC_REST_BUFFER_TOO_SMALL if the string is larger than the provided buffer.
retcode_t RestParser_getUriQuery ( RestParser_T parser_ptr,
char *  buffer_ptr,
uint8_t  bufferLen 
)

This function retrieves the URI Query as a string of an incoming message.

Parameters
[in]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[out]buffer_ptrReference to the buffer which is provided for storing the URI Query. The returned string is null terminated.
[in]bufferLenLength of the allocated buffer which is provided to store the URI Query.
Returns
RC_OK if successful
RC_REST_BUFFER_TOO_SMALL if the string is larger than the provided buffer.
void RestParser_setup ( RestParser_T parser_ptr,
Msg_T msg_ptr 
)

This function is called to initialize the context of the REST parser for parsing a given message.

Parameters
[out]parser_ptrReference to a RestParser_T object which identifies the instance of parsing context which should be setup. It has to be a valid pointer.
[in]msg_ptrPointer to message which should be parsed. The content will not be changed. It has to be a valid pointer.

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:46 by doxygen 1.8.8