XDK API  3.6.0
Documentation
Macros
Serval_Policy.h File Reference

Definition of backward compatibility. More...

+ This graph shows which files directly or indirectly include this file:

Macros

#define SERVAL_POLICY_COAP_EXPLICIT_ERROR_CODES   1
 
#define SERVAL_POLICY_COAP_REMOVE_SERIALIZER_OPTION_COUNT   1
 
#define SERVAL_POLICY_COAP_STRICT_TOKEN_API   0
 
#define SERVAL_POLICY_DPWS_PRIVATE_MSG_CLOSE   1
 
#define SERVAL_POLICY_HTTP_AUTHENTICATION_CALLBACK   0
 
#define SERVAL_POLICY_LARGE_PAYLOAD   0
 
#define SERVAL_POLICY_LWM2M_DEFAULT_TO_IANA_DEFINED_TLV_FORMAT_NUMBER   1
 
#define SERVAL_POLICY_LWM2M_DROP_DEPRECATED_FORMATS   0
 
#define SERVAL_POLICY_LWM2M_INCLUDE_SERVER_IN_CALLBACK   0
 
#define SERVAL_POLICY_LWM2M_MULTIPLE_SERVICES   0
 
#define SERVAL_POLICY_PAL_LOG_CONSTRUCTION   0
 
#define SERVAL_POLICY_PRIVATE_MSG_API   1
 
#define SERVAL_POLICY_REMOVE_CB_PTR_FROM_SENDING_CTX   1
 
#define SERVAL_POLICY_REMOVE_GENERIC_APP_CALLBACK_API   0
 
#define SERVAL_POLICY_REMOVE_MSG_RESPOND   1
 
#define SERVAL_POLICY_REMOVE_MSG_TYPE_ACCESSORS   0
 
#define SERVAL_POLICY_REMOVE_SPECIALIZED_ACCESSORS_FROM_MSG_H   1
 
#define SERVAL_POLICY_REMOVE_TLPMSG   1
 
#define SERVAL_POLICY_SENDING_CONTEXT_IN_PAL   1
 

Detailed Description

The Serval communication stack provides API compatibility within the major releases. However, improvements to the stack can sometimes require an API change that is not backwards compatible. In these cases the notion of a policy is used in order to allow the new API to be introduced while still maintaining backwards compatibility.

A policy is thus a set of changes to the API or the way the API is used that, if turned on, will provide a more optimized API (in terms of either use or in terms of resource consumption). Policies are API changes that are likely to become part of the official API and thus provide a good preview mechanism for the next major release.

By default, the stack will remain API compatible with previous versions of the same major version. By enabling a particular policy, you explicitly forego this backward compatibility in order to a) use new features enabled by this policy or b) to test if your code is affected by a particular API change.

Policies are not typically disabled by default as to not affect existing applications. There are exceptions to this rule that fix API irregularities where elements have become public API that were not meant to be public API, have no good reason to be public API and cannot really be used for any particular productive purpose. Thus it is assumed that applications have not used these features. Currently there are several such policies: *) SERVAL_POLICY_COAP_REMOVE_SERIALIZER_OPTION_COUNT *) SERVAL_POLICY_REMOVE_TLPMSG *) SERVAL_POLICY_REMOVE_SPECIALIZED_ACCESSORS_FROM_MSG_H *) SERVAL_POLICY_REMOVE_MSG_RESPOND *) SERVAL_POLICY_PRIVATE_MSG_API *) SERVAL_POLICY_SENDING_CONTEXT_IN_PAL *) SERVAL_POLICY_REMOVE_CB_PTR_FROM_SENDING_CTX

Set SERVAL_POLICY_FULL_COMPATIBILITY_1_2 to force the stack to be compatible with the interface provided by the stack version 1.2.x

Set SERVAL_POLICY_FULL_API_PREVIEW_2_0 in order to preview the API changes for 2.0

Since
1.3

Macro Definition Documentation

#define SERVAL_POLICY_COAP_EXPLICIT_ERROR_CODES   1

The CoAP layer hides certain error conditions behind generic ones, such as RC_COAP_SENDING_ERROR. This policy disables this behavior and passes the original error codes up to the application in order to allow more fine-grained application responses to error codes.

Enabled by default, since a check for status != RC_OK is most likely to be done in the applications, anyways.

#define SERVAL_POLICY_COAP_REMOVE_SERIALIZER_OPTION_COUNT   1

The COAP_OPTION_COUNT policy provides backwards compatibility with the count for serialized options. This is a remnant of the old coap-12 option construction. In particular, this policy allows access to the optionSerializeCount field in Coap_Serializer_T. This struct appears in an API header but is not really meant to be used for any more than an opaque type. The use of this field is highly discouraged. For this reason, this policy is enabled by default.

Since
1.3
#define SERVAL_POLICY_COAP_STRICT_TOKEN_API   0

The COAP_STRICT_TOKEN_API policy enforces proper use of the new token API of the CoAP parser and serializer added in patch 1.3.

In particular:

  • CoapParser now has an API to retrieve the token
  • The option COAP_TOKEN no longer exists.

Porting the API to this policy is only required if the CoAP API is used directly. The REST API already uses the new API internally. The porting process is fairly straightforward. The main task is to handle the TOKEN correctly. In the old API, the token was set and retrieved using the COAP_TOKEN option. For implementations setting the token, the token needs to be set using CoapSerializer_serializeToken() before setting an option. For implementations retrieving the Token, CoapParser provides the function CoapParser_getToken with which the token can be retrieved. The code that parses the options for the token can then be deleted.

Since 1.8, this new API is mandatory for not wanting to serialize a token. Otherwise, per default a 2 byte token is generated for requests. Not setting a token by default has led to too many errors.

Since
1.3
#define SERVAL_POLICY_DPWS_PRIVATE_MSG_CLOSE   1

Make DpwsMsg_close function private

The common case is to use Msg_close for closing the message.

Enabled by default.

Since
1.3
#define SERVAL_POLICY_HTTP_AUTHENTICATION_CALLBACK   0

The original HTTP Authentication implementation required a table to be supplied to the stack. This fixed the data structure and prevented additional information to be stored alongside it and also prevented the application from implementing any brute-force countermeasures. This policy changes this mechanism by requiring the application to provide a callback that handles user authentication using utility functions provided by the stack.

#define SERVAL_POLICY_LARGE_PAYLOAD   0

The original implementation of the CoAP and Rest parsers only allowed a payload of 256 bytes since the data type storing the length of the payload was only 8 bits long. This policy extends the length of this data type to 16 bits.

Since
1.3
#define SERVAL_POLICY_LWM2M_DEFAULT_TO_IANA_DEFINED_TLV_FORMAT_NUMBER   1

The Lwm2m implementation of the stack has been started when the TLV format of Lwm2m did not have its own number assigned by the IETF. The leshan project, somewhat arbitrarily, defined format numbers and assigned 1542 to TLV internally. Due to Leshan being Open Source, this number has seen some adoption. Unfortunately, when the content format was registered, 1542 well into a reserved area of numbers and thus a different number, 11542 was assigned.

If no accept option is specified, thus indicating that any content type is to be accepted, the stack defaults to sending TLV encoded content. Starting from 1.7, it uses the IANA defined number for the TLV concent. Unset this policy in order to revert to the old, leshan defined content number.

Since
1.7
#define SERVAL_POLICY_LWM2M_DROP_DEPRECATED_FORMATS   0

The Lwm2m implementation of the stack has been started when the formats of Lwm2m did not have their own number assigned by the IANA. The leshan project, somewhat arbitrarily, defined format numbers. These numbers were in a range for testing only and thus different numbers were assigned when actually registering the formats.

This policy drops support for the deprecated numbers. Implicitly, this also forces SERVAL_POLICY_LWM2M_IANA_DEFINED_TLV_FORMAT_NUMBER

Since
1.7
#define SERVAL_POLICY_LWM2M_INCLUDE_SERVER_IN_CALLBACK   0

The original Lwm2m implementation did not include the server in its callbacks. This made it impossible to distinguish the actions of one server from another. This policy extends the Lwm2m callback by a server field.

Since
1.10
#define SERVAL_POLICY_LWM2M_MULTIPLE_SERVICES   0

The original Lwm2m implementation was designed around starting either a secure or an unsecure device, but not both concurrently.

In 1.8, Lwm2m_startService(...) was introduced that offers this functionality. However, this duplicates somewhat the secure flag in Lwm2mDevice_T, which is thus deprecated.

This policy drops support for this secure flag, since realistically, the security cannot be guaranteed any longer if Lwm2m_startService(...) is used.

#define SERVAL_POLICY_PAL_LOG_CONSTRUCTION   0

The current logging API constructs log messages before passing them into the log appender for processing. This requires an explicit buffer (logbuf) in the stack for generation of these messages and also prevents the PAL from making decisions based on the severity of the log messages (e.g. print errors in red).

This policy changes the signature of the log appender to allow passing messages directly to this log appender.

It also makes the construction of the message header accessible to the PAL.

Since
1.6
#define SERVAL_POLICY_PRIVATE_MSG_API   1

Removes several functions from the public message API that are currently not used directly and are not useful to the application if used directly.

*) typedef struct OutMsgFactory_S OutMsgFactory_T; *) void Msg_open(Msg_T <em>msg_ptr); *) OutMsgFactory_T *Msg_getFactory(Msg_T *msg_ptr); *) void Msg_releaseCommBuf(Msg_T *msg_ptr); *) void Msg_callbackApp(Msg_T *msg_ptr, retcode_t status); *) Msg_T *Msg_getContext(Callable_T *callable_ptr); *) void Msg_setTLP(Msg_T msg_ptr, Msg_TLP_T tlp); *) void Msg_setALP(Msg_T *msg_ptr, Msg_ALP_T alp);

Enabled by default.

Since
1.5
#define SERVAL_POLICY_REMOVE_CB_PTR_FROM_SENDING_CTX   1

Removes the field callback_ptr from the Message sending Context. It should not be required by the PAL in either prepareForSending or retrySendingLater which are the only consumers of this structure.

Enabled by default.

Since
1.3
#define SERVAL_POLICY_REMOVE_GENERIC_APP_CALLBACK_API   0

Remove the generic function Msg_setAppCallback. It should be provided by the respective protocol API.

Since
1.3
#define SERVAL_POLICY_REMOVE_MSG_RESPOND   1

Removes the generic Msg_respond functionality. Protocols should know themselves how to respond to a particular message and there currently isn't functionality in the stack that responds to generic messages, the application layer is always involved. The only user is the generated code in applications using DPWS. Making it compatible requires a regeneration of the code with a recent code generator. Enabled by default

Since
1.5
#define SERVAL_POLICY_REMOVE_MSG_TYPE_ACCESSORS   0

Removes the message type from the message structure and the corresponding accessors. This functionality should be provided by protocols that requires this information.

Since
1.3
#define SERVAL_POLICY_REMOVE_SPECIALIZED_ACCESSORS_FROM_MSG_H   1

Currently, all specialized messages are accessed via Serval_Msg.h. In order to focus protocol implementation on modules, this functionality is moved to the respective protocol modules. It should not affect existing applications, since they would include the specialized header files when using a particular protocol.

Since
1.5
#define SERVAL_POLICY_REMOVE_TLPMSG   1

The TLPMsg is a data structure that provides access to the Transport Layer Message. This data structure has been removed during internal restructuring. However, the public API of the stack allowed access to a pointer to this data structure. This feature has proven to not be overly useful and has not been used in applications so far. In fact its use is highly discouraged since it can greatly affect stability and message delivery. Furthermore the public API does not offer any use for this data structure. De facto, it cannot be used by the application. For this reason the policy is enabled by default.

Since
1.5
#define SERVAL_POLICY_SENDING_CONTEXT_IN_PAL   1

Move the MsgSendingCtx structure from a publicly visible API in Serval_Msg.h to the PAL.

The intend of this structure is to communicate with the PAL Udp/Tcp prepareForSending and retrySendingLater functions. It is not a direct application API.

Enabled by default.

Since
1.5

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