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

An interface to the Messaging Module.This interface provides type definitions, data types and functions to handle messages. More...

#include <Serval_Defines.h>
#include <Serval_Types.h>
#include <Serval_StringDescr.h>
#include <Serval_XmlParser.h>
#include <Serval_Filesystem.h>
#include <Serval_Callable.h>
#include <Serval_Ip.h>
#include <Serval_Policy.h>
#include <Serval_Msg_Obsolete.h>
+ Include dependency graph for Serval_Msg.h:
+ This graph shows which files directly or indirectly include this file:

Data Structures

struct  AppInOutput_Manager_S
 
struct  ContentBase_S
 
struct  ContentHandle_S
 
struct  OutMsgRecipe_S
 
struct  OutMsgSerializationHandover_S
 

Macros

#define CB_DYNAMIC(index)   ( (index) & ~0xC0 )
 
#define CB_EXTERNAL(index)   ( (index) | 0x80 )
 
#define CB_STATIC(index)   ( ((index) & ~0x80) | ((index) | 0x40) )
 
#define SERVAL_MAX_NUM_MSG_PARTS   6
 
#define SERVAL_MSG_MONITOR_TIMEOUT   2000
 
#define SERVAL_MSG_MONITOR_TRACE_TIMEOUT   (SERVAL_MSG_MONITOR_TIMEOUT * (1 + SERVAL_LOG_LEVEL/3))
 

Typedefs

typedef AppSentCallback_T AppCallback_T
 
typedef retcode_t(* AppInOutput_AllocInputFunc_T )(AppInput_T **)
 
typedef retcode_t(* AppInOutput_AllocOutputFunc_T )(AppOutput_T **)
 
typedef struct
AppInOutput_Manager_S 
AppInOutput_Manager_T
 
typedef retcode_t(* AppInOutput_ReleaseInputFunc_T )(AppInput_T *)
 
typedef retcode_t(* AppInOutput_ReleaseOutputFunc_T )(AppOutput_T *)
 
typedef union AppInput_U AppInput_T
 
typedef union AppOutput_U AppOutput_T
 
typedef void(* AppSentCallback_T )(Msg_T *msg_ptr, retcode_t status)
 
typedef struct ContentBase_S ContentBase_T
 
typedef struct ContentHandle_S ContentHandle_T
 
typedef retcode_t(* DynamicContent_T )(OutMsgSerializationHandover_T *)
 
typedef struct Msg_S Msg_T
 
typedef retcode_t(* MsgOnSentCallback_T )(Msg_T *msg_ptr, retcode_t status)
 
typedef retcode_t(* OutMsgPartFactoryFunc_T )(OutMsgSerializationHandover_T *)
 
typedef struct OutMsgRecipe_S OutMsgRecipe_T
 
typedef struct
OutMsgSerializationHandover_S 
OutMsgSerializationHandover_T
 
typedef uint8_t const * RecipeTable_T
 

Functions

void Msg_close (Msg_T *msg_ptr)
 
Callable_TMsg_defineCallback (Msg_T *msg_ptr, CallableFunc_T callback)
 
Callable_TMsg_getCallback (Msg_T *msg_ptr)
 
retcode_t TcpMsg_copyContentAtomic (OutMsgSerializationHandover_T *omsh_ptr, const void *content, uint16_t contentLength)
 
retcode_t TcpMsg_copyStaticContent (OutMsgSerializationHandover_T *omsh_ptr, const void *content, uint16_t contentLength)
 
retcode_t TcpMsg_prependPartFactory (Msg_T *msg_ptr, OutMsgPartFactoryFunc_T partFactoryFunc_ptr)
 

Macro Definition Documentation

#define CB_DYNAMIC (   index)    ( (index) & ~0xC0 )
#define CB_EXTERNAL (   index)    ( (index) | 0x80 )
#define CB_STATIC (   index)    ( ((index) & ~0x80) | ((index) | 0x40) )
#define SERVAL_MAX_NUM_MSG_PARTS   6

The threshold on the number of message part factories. Notice that an OutMsgFactory consists of a list of part factories which are responsible for serializing the message parts.

#define SERVAL_MSG_MONITOR_TIMEOUT   2000

define the timeout in ms for garbage collection of messages it must be a Multiple of RESOURCE_MONITOR_PERIODE

#define SERVAL_MSG_MONITOR_TRACE_TIMEOUT   (SERVAL_MSG_MONITOR_TIMEOUT * (1 + SERVAL_LOG_LEVEL/3))

Typedef Documentation

A data type representing a callback function pointer for application. The application uses such callback functions in order to be notified about the sending result of outgoing messages.

Deprecated:
The type AppSentCallback_T should be used instead.
typedef retcode_t(* AppInOutput_AllocInputFunc_T)(AppInput_T **)
typedef retcode_t(* AppInOutput_AllocOutputFunc_T)(AppOutput_T **)

The data structure which holds all functions to manage application's input and output objects.

See also
struct AppInOutput_Manager_S
typedef retcode_t(* AppInOutput_ReleaseInputFunc_T)(AppInput_T *)
typedef retcode_t(* AppInOutput_ReleaseOutputFunc_T)(AppOutput_T *)
typedef union AppInput_U AppInput_T

A data type that represents application's input object.

Notice that the union itself is defined in the application.

See also
union AppInput_U
typedef union AppOutput_U AppOutput_T

A data type that represents application's output object.

Notice that the union itself is defined in the application.

See also
union AppOutput_U
typedef void(* AppSentCallback_T)(Msg_T *msg_ptr, retcode_t status)

A data type representing a callback function pointer for application. The application uses such callback functions in order to be notified about the sending result of outgoing messages.

typedef struct ContentBase_S ContentBase_T

This holds the information about various content bases from where a message will be constructed using message recipe.

See also
struct ContentBase_S

This represents a handle for a content from content base.

See also
struct ContentHandle_S
typedef retcode_t(* DynamicContent_T)(OutMsgSerializationHandover_T *)

A data type for functions which serialize a dynamic content of an outgoing message. The OutMsgSerializationHandover_T object handed in as a a parameter encapsulates all input and output information which might be needed by the function. The function should serialize the content into the buffer given in the OutMsgSerializationHandover_T object and return RC_OK. The field bufLen gives the maximal length which the function is allowed to write into the buffer. If the bufLen is too small to serialize the entire content, then no bytes should be written and the function should return RC_MSG_FACTORY_INCOMPLETE. The function must set the field len to the number of written bytes. Both offset and position must not be touched by the function.

typedef struct Msg_S Msg_T

Message Data Types The data structure for a messaging context. An element of this struct represents the context of a messaging session of any supported pattern, e.g. Request/Response, Request/No-Response, ... This means, it holds all information about a complete communication cycle, rather than just one message.

See also
struct Msg_S
typedef retcode_t(* MsgOnSentCallback_T)(Msg_T *msg_ptr, retcode_t status)

A data type representing a callback function pointer to inform an upper layer that the lower layer has completed sending the message.

typedef retcode_t(* OutMsgPartFactoryFunc_T)(OutMsgSerializationHandover_T *)

A data type for message part factory functions. These are function which are responsible for serializing a part of an outgoing message. An OutMsgFactory_T object consists of a list of such part factories. The OutMsgSerializationHandover_T object handed in as a a parameter encapsulates all input and output information which might be needed by the part factory. The part factory should serialize the content into the buffer given in the OutMsgSerializationHandover_T object and return RC_OK. The field bufLen gives the maximal length which the function is allowed to write into the buffer. If the bufLen is too small to serialize the entire content, then the part factory can serialize a segment of its part and return RC_MSG_FACTORY_INCOMPLETE. Both fields offset and position can be used by the part factory in order to mark the position at which it should start the serialization in the next chunk. In any case, the function must set the field len to the number of written bytes.

This represents a recipe for outgoing message construction.

See also
struct OutMsgRecipe_S

This data structure is used hold the buffer and information needed by the serializer to append the data at the right place.

See also
struct OutMsgSerializationHandover_S
typedef uint8_t const* RecipeTable_T

This represents a recipe for message construction. It is a list of entries. Each entry references an element of a given content base. Notice that a recipe is only defined in relation to a certain content base. Each entry of the recipe consists of 8 bits. If the most significant bit is set to 1, then the entry is interpreted as a reference to an external element of the content base. The remaining 7 bits indicate the index of the element in the external elements table. If the most significant bit is 0 and the following bit is set to 1, then the entry is interpreted as a reference to a static element of the content base. The remaining 6 bits indicate the index of the element in the static elements table. If both most significant 2 bits are 0, then the entry is interpreted as a reference to a dynamic element of the content base. The remaining 6 bits indicate the index of the element in the dynamic elements table.

This scheme results in that the recipe can reference at most 128 external elements, 64 static elements, and 64 dynamic elements.

use the macros CB_EXTERNAL, CB_STATIC, CB_DYNAMIC for easier access (since 1.5)

See also
ContentBase_T

Function Documentation

void Msg_close ( Msg_T msg_ptr)

This function is called to close a previously allocated message. After this call the message will be released form the message pool.

Parameters
[in]msg_ptrReference to a Msg_T object which holds the message to be closed. It has to be a valid pointer.
Callable_T* Msg_defineCallback ( Msg_T msg_ptr,
CallableFunc_T  callback 
)

This function is called to initialize callback in the given message. This callback will be invoked to signal completion of sending.

Parameters
[in]msg_ptrReference to a Msg_T object which holds the current message. It has to be a valid pointer.
[in]callbackReference to a CallableFunc_T object, this holds the callback to be assigned.
Callable_T* Msg_getCallback ( Msg_T msg_ptr)
retcode_t TcpMsg_copyContentAtomic ( OutMsgSerializationHandover_T omsh_ptr,
const void *  content,
uint16_t  contentLength 
)

Serialize content of length contentLength into the buffer contained in omsh_ptr. If the buffer can hold the entire content, RC_OK is returned. However, in contrast to TcpMsg_copyStaticContent, if the content does not fit, no data is written to the buffer and RC_MSG_FACTORY_INCOMPLETE is returned.

It is expected, that the calling function will return this error code to its caller, triggering a further call by the message serialization core. In that call, TcpMsg_copyContentAtomic must me called with precisely the same values for content and contentLength in order to resume serialization.

Parameters
[in]omsh_ptrThe structure holding serialization information such as the maximum size or the current position of the data.
See also
OutMsgSerializationHandover_T.
Parameters
[in]contentThe content to be copied into the message
[in]contentLengthThe length of the content to be serialized
Returns
RC_OK if the content has been copied completely RC_MSG_FACTORY_INCOMPLETE if only parts of the content have been copied
retcode_t TcpMsg_copyStaticContent ( OutMsgSerializationHandover_T omsh_ptr,
const void *  content,
uint16_t  contentLength 
)

Serialize content of length contentLength into the buffer contained in omsh_ptr. If the buffer can hold the entire content, RC_OK is returned. If the content does not fit, part of the content is copied into the message, the offset field of omsh_ptr is manipulated to store the amount of already serialized content for a subsequent call, and RC_MSG_FACTORY_INCOMPLETE is returned.

It is expected, that the calling function will return this error code to its caller, triggering a further call by the message serialization core. In that call, TcpMsg_copyStaticContent must me called with precisely the same values for content and contentLength in order to resume serialization.

Parameters
[in]omsh_ptrThe structure holding serialization information such as the maximum size or the current position of the data.
See also
OutMsgSerializationHandover_T.
Parameters
[in]contentThe content to be copied into the message
[in]contentLengthThe length of the content to be serialized
Returns
RC_OK if the content has been copied completely RC_MSG_FACTORY_INCOMPLETE if only parts of the content have been copied
retcode_t TcpMsg_prependPartFactory ( Msg_T msg_ptr,
OutMsgPartFactoryFunc_T  partFactoryFunc_ptr 
)

This function adds a function to the factory of the given message, that should add or modify the current data in the buffer by serializing a specific recipe or adding a header or ending etc...

Parameters
[in]msg_ptrPointer to the message.
[in]partFactoryFunc_ptrThe function pointer that should be added to the list of part factory functions.
Returns
RC_OK
RC_MSG_FACTORY_SIZE_ERROR if there is no place to accommodate the new part factory.
RC_MSG_FACTORY_ALREADY_COMMITTED if the factory is already committed.

+ Here is the caller graph for this function:


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