To allow multiple higher-level communication modules to be added, Panda uses a two level naming scheme. The first level is the platform identifier (or platform set for multicast operations), which specifies the destination platform(s). The second level is the network service access point, which identifies the service a fragment is destinated for. Every higher-level module that does communication creates one or more access points. To facilitate addressing, all network service access points have to be acquired before pan_start is called, so all access points are acquired in the same order on all platforms. The sap specifies the upcall function to be used.
typedef int (*pan_receive_f)(void *data, int size, int len);
Network service access point receive handler type. The receive function gets as arguments a pointer to the received data, the size of the data buffer, and the actual length of the data received.
The receive function returns a boolean specifying whether the data buffer is kept at the receive function level (1) or can be reused at the system level (0). If the buffer is kept at the receive function level, it must be released with pan_free. An exception to this rule is the local upcall in pan_multicast. Since the data pointer passed to pan_multicast is delivered, the receive handler function may only return 1 on the sender side.
The system layer guarantees that size - len >= pan_sap_trailer(sap).
IMPORTANT: The upcall is not allowed to block on a condition synchronization, only on short-term mutex synchronization (lock/unlock). Furthermore, multiple instances of the upcall may be active at the same time.
#define PAN_SAP_UNICAST 0x01 #define PAN_SAP_MULTICAST 0x02
pan_sap_p pan_sap_create(pan_receive_f receive, int flags);
Create a new network service access point. Data received on this sap are handled with an upcall to receive. flags specifies the type of communication sap is going to be used for (PAN_SAP_UNICAST, PAN_SAP_MULTICAST).
void pan_sap_clear(pan_sap_p sap);
Clear network service access point sap.
int pan_sap_trailer(pan_sap_p sap);
Returns the space that the sender has to reserve for a trailer after the user data. The system layer uses this space to add information for demultiplexing and routing. The data in the buffer where the trailer will be put may not be accessed during a call to unicast/multicast. The original data in this area is restored when the send call returns.
int pan_sap_id(pan_sap_p sap);
Return a globally unique identifier for sap. The identifiers are numbered consecutively starting from 0.
pan_sap_p pan_sap_locate(int id);
Return the sap with globally unique identifier id.