Data Types (guile-netlink)

2.1.1 Data Types

Guile-netlink defines data types that are used in the various Netlink protocols. We need to be able to serialize and deserialize data that guile-netlink understands, but we also want to let users of guile-netlink extend this process easily. This need has lead to the creating of the following data structure, defined in (netlink data).

Datatype: nl-data ¶

data: The data that is held by this record.
size-proc: A procedure that takes a data (of the same type as the data recorded in the data field) and returns the size of its serialization.
serialization-proc: A procedure that takes a data (of the same type as the data recorded in the data field), the position at which to start serializing, and a bytevector in which to serialize. This procedure should modify the bytevector and its return value is ignored.

The module also defines the following function, that takes a nl-data structure and provides its serialization in a bytevector:

Scheme Procedure: serialize data pos bv ¶

Takes a nl-data structure as data, a position pos in the bytevector bv, and returns an unspecified value.

This function updates the bytevector and adds the serialization of data into bv at pos.

By providing a nl-data structure, we defer the knowledge of how to serialize the data to the structure itself, instead of the serialize function. This allows for more flexibility and extensibility, as the user of the procedure can pass any kind of data, even if it is not yet supported by guile-netlink.

Similarly, we need to be able to deserialize netlink answers into a data structure. To do so, we also defer the knowledge of the datastructure to deserialize to, to a decoder structure that is passed to the deserialization procedure. (netlink data) also defines the following procedures to deserialize data:

Scheme Procedure: deserialize type decoder bv pos ¶

Takes a bytevector bv and starts deserializing the data starting at position pos. To do so, it uses the type variable as the lookup key in the decoder. type is a symbol that represents the type of data to deserialize to.

The decoder is a structure that associates each known type to its deserializer (a function that takes a decoder, a bytevector and a position and returns some data) and an alist that associates a type (an integer, as returned by the protocol in use) to the proper decoder of that type.

Scheme Procedure: get-current-deserialize decoder current-type ¶: Takes a decoder and a type, and returns the deserialization procedure associated with the type (a symbol) in decoder.

Scheme Procedure: get-next-deserialize decoder current-type target-type ¶

Takes a decoder, a type (a symbol that represents the type of data being deserialized) and another type (an integer as returned by the protocol), and returns the deserialization procedure needed to continue decoding the data associated with the currently being deserialized data.

For example, when decoding an answer in the netlink protocol, we first deserialize the header into a message structure. That header contains a type field that contains an integer constant representing the type of data of the body. Similarly, when deserializing a routing attribute in the rtnetlink protocol, we first find a header of the attribute that defines an integer constant corresponding to the type of attribute in the body.

By knowing the context in which the type is declared, this procedure can return the correct deserializing procedure. For instance, when deserializing a message, type 16 means RTM_NEWLINK in the rtnetlink protocol, whereas it means IFLA_OPERSTATE when deserializing a route-attribute.

guile-netlink provides the following default decoder for the rtnetlink protocol in (netlink deserialize):

Scheme Variable: %default-route-decoder ¶: Contains the default decoder for the NETLINK_ROUTE protocol.

For convenience, guile-netlink defines the following structures that can be used to create a custom decoder.

Scheme Variable: %default-message-decoder ¶: Contains the default association list for the common message types of netlink, associating each of them to a deserialization procedure.

Scheme Procedure: default-route-attr-decoder deserialize-addr ¶: Creates the default association list for a route protocol, given the specified address deserializer. This is useful because the IFA_ADDRESS, IFA_BROADCAST, etc, contain a different type of address depending on the message type or its header. This is defined an (netlink route attrs) and used by the following variables:

Scheme Variable: %default-route-link-attr-decoder ¶: Contains the default association list for the known types of routing attributes for link messages. This list is defined in (netlink route attrs).