Ucs_AmsTx_Msg_t* Ucs_AmsTx_AllocMsg	(	Ucs_Inst_t *	self,
		uint16_t	data_size
	)

Allocates an application message object for transmission.

This function retrieves a Tx message object with a payload buffer of the given size. The application must take care that Ucs_AmsTx_Msg_t::data_size of the resulting message object does not exceed the amount of provided payload.
The application is also allowed to provide own payload to the message object. In this case the application is allowed to call this function and pass data_size "0". The application can set Ucs_AmsTx_Msg_t::data_ptr and Ucs_AmsTx_Msg_t::data_size of the returned message object to the application provided payload.

Parameters

self	The instance
data_size	Required payload size which needs to be allocated. Valid values: 0..65535.

Returns

The allocated Tx message object or NULL if no Tx message object is available. If the function returns NULL the application can use ams.tx.message_freed_fptr as trigger to request a message object again.
Please note that the function also returns NULL if the current Supervisor Mode does not allow the execution, or the AMS feature is disabled either by defining UCS_FOOTPRINT_DISABLE_AMS or by setting the initialization attribute ams.enabled to false. In the first case it is recommended to re-trigger this function if the Supervisor Mode alters to a valid one.

Note

The application may also allocate a certain number of message objects without transmitting in one go. In this case the message object is handed over to the application which is now responsible to transmit or free the object. When UNICENS terminates it is possible that user allocated memory is still dedicated to such a message buffer. In this case the application must do the following steps for every retained Tx message object:

• Free application provided payload
• Call Ucs_AmsTx_FreeUnusedMsg() to release the message to UNICENS
• Guarantee to access the Tx message object never again

After performing these steps the application is allowed to call Ucs_Init() again.