Serialization and Deserialization of Real Payload at the TCP Layer
TCP payload data needs to be converted to a string of characters and stored in the segmentation and reassembly buffers. These strings of characters, when transmitted as packet payload, are represented as bits on the wire.The payload must be serialized as it enters the buffer on the transmitting node and then deserialized at the receiving node when it is passed out of the buffer, as described in this section.
Note: You must register the serialization and deserialization callback functions.
Serialization of Real Payload
To serialize the real payload, the callback function first creates a payload handle by specifying an approximate size for the buffer that temporarily holds the serialized contents of the payload. The callback then serializes the data by calling the appropriate API (based on the data type being serialized). When all the data has been serialized and stored in the temporary buffer, the callback function calls oms_sar_payload_serialized_bytes_get to get the serialized bytes, which is used to the fill in the buffer that is passed in to the callback.
Deserialization of Real Payload
To deserialize the real payload, the deserialization callback creates a payload handle by passing in the string of bytes to be deserialized. Then the callback calls the APIs in the same sequence in which they were serialized to convert the string of bytes into data of the appropriate type. The callback then creates packets of the required type, fills in the data obtained by deserializing the payload, and returns a packet.
Note: When a client of the SAR package (TCP, for instance) requests data to be accessed or removed from the buffer, the amount of data requested must be a multiple of 8 bits. If it is not a multiple of 8, then the SAR package will create a segment whose bit count is the closest multiple of 8, but smaller than the requested size.
Sample Serialization/Deserialization Functions of Real Payload
The example below shows how to program the serialization and deserialization functions.
Compcode
tcp_sar_serialization_callback (Packet* packet, char **data_arr,
OpT_Packet_Size *array_size)
{
OmsT_Payload_Handle *payload_handle_ptr = OPC_NIL;
int tos = 0, options = 0;
double ratio = 0.0;
FIN (tcp_sar_serialization_callback);
/* Create the payload handle. */
payload_handle_ptr = oms_sar_payload_serializer_handle_create (
op_pk_total_size_get (packet));
/* Serialize the data from the packet. */
/* Get the data from the packets. */
op_pk_nfd_get_int32 (packet, "Type of Service", &tos);
op_pk_nfd_get_int32 (packet, "Options", &options);
op_pk_nfd_get_dbl (packet, "Ratio", &ratio);
/* Store the serialized data in the buffer. */
oms_sar_payload_int32_serialize (payload_handle_ptr, tos);
oms_sar_payload_int32_serialize (payload_handle_ptr, options);
oms_sar_payload_double_serialize (payload_handle_ptr, ratio);
/* Get the serialized data from the buffer. */
oms_sar_payload_serialized_bytes_get (payload_handle_ptr, data_arr,
array_size);
/* Destroy the payload handle */
oms_sar_payload_handle_destroy (&payload_handle_ptr);
FRET (OPC_COMPCODE_SUCCESS);
}
Packet*
tcp_sar_deserialization_callback (char *data_arr, OpT_Int64 array_size,
OpT_Packet_Size *data_converted)
{
OmsT_Payload_Handle *payload_handle_ptr = OPC_NIL;
int tos = 0, options = 0;
double ratio = 0.0;
Packet *packet_ptr = OPC_NIL;
FIN (tcp_sar_deserialization_callback);
/* Create the payload handle. */
payload_handle_ptr = oms_sar_payload_deserializer_handle_create (
data_arr, array_size);
/* Get the data from the payload. */
oms_sar_payload_int32_deserialize (payload_handle_ptr, &tos);
oms_sar_payload_int32_deserialize (payload_handle_ptr, &options);
oms_sar_payload_double_deserialize (payload_handle_ptr, &ratio);
/* Create a packet of the required type and fill in the data. */
packet_ptr = op_pk_create_fmt ("tcp_data_packet");
if (packet_ptr)
{
op_pk_nfd_set_int32 (packet_ptr, "Type of Service", tos);
op_pk_nfd_set_int32 (packet_ptr, "Options", options);
op_pk_nfd_set_dbl (packet_ptr, "Ratio", ratio);
}
/* Fill in the number of bytes of payload deserialized. */
*data_converted = sizeof(int)*2 + sizeof(double);
/* Destroy the payload handle */
oms_sar_payload_handle_destroy (&payload_handle_ptr);
FRET (packet_ptr);
}
These functions should be defined in an ex.cpp file and oms_sar_payload_support.h must be included in this file. This file must also be declared in the simulation scenario or in the related process model, using File > Declare External Files. Note that one serialization and one deserialization callback can be registered per TCP connection. If the client is sending multiple types of packets, these should be handled within the same callback.
Registering the Serialization/Deserialization Functions for Real Payload
A client of TCP must register the serialization and deserialization callbacks for real payload.
If the client is using InetT_Address structures, the client must open TCP connections using the following API:
tcp_connection_open_with_options(ApiT_Tcp_App_Handle* tcp_hndl_ptr,
InetT_Address rem_addr, TcpT_Port remote_port, int command,
TcpT_Conn_Open_Options* options)
In the TcpT_Conn_Open_Options structure passed in, the client should set the serialization and deserialization callbacks:
options->ser_callbacks_ptr->serialize_func = tcp_sar_serialization_callback;
options->ser_callbacks_ptr->deserialize_func =
tcp_sar_deserialization_callback;
Note: To create InetT_Address structures, you can use the inet_address_create (const char* ip_addr_str, InetT_Addr_Family addr_family) API.
If the client is using IpT_Address structures, the client must open TCP connections using the following API:
tcp_connection_with_source_open_core (ApiT_Tcp_App_Handle*
tcp_hndl_ptr, IpT_Address rem_addr, TcpT_Port rem_port, IpT_Address
local_addr, TcpT_Port loc_port, int command, int ip_qos,
OmsT_Sar_Packet_Serialize_Cback ser_func,
OmsT_Sar_Packet_Deserialize_Cback deser_func)
Note: To create IpT_Address structures, you can use the ip_address_create (const char *addr_str) API.
Note that tcp_sar_serialization_callback and tcp_sar_deserialization_callback are just examples. It could be any function name that you create in the previous section of this document.
For more information about these APIs, please refer to the ip_addr_v4 external source model.