wimax-tools  1.4.4
Typedefs | Functions
The message interface

This is a payload agnostic message interface for communication between the WiMAX kernel drivers and user space applications. More...

Typedefs

typedef int(* wimaxll_msg_to_user_cb_f )(struct wimaxll_handle *wmx, void *priv, const char *pipe_name, const void *data, size_t size)
 Callback for a message to user generic netlink message. More...
 

Functions

ssize_t wimaxll_msg_read (struct wimaxll_handle *wmx, const char *pipe_name, void **buf)
 Read a message from any WiMAX kernel-user pipe. More...
 
void wimaxll_msg_free (void *msg)
 Free a message received with wimaxll_msg_read() More...
 
ssize_t wimaxll_msg_write (struct wimaxll_handle *wmx, const char *pipe_name, const void *buf, size_t size)
 Send a driver-specific message to a WiMAX device. More...
 
int wimaxll_recv_fd (struct wimaxll_handle *wmx)
 Return the file descriptor associated to a WiMAX handle. More...
 

Detailed Description

This is a payload agnostic message interface for communication between the WiMAX kernel drivers and user space applications.

It writes messages (wimax_msg_write()) by sending them to the WiMAX kernel stack, which passes it to the driver using the wimax_dev->op_msg_from_user() call.

To write messages to the driver:

* wimaxll_msg_write(wmx, PIPE_NAME, buf, buf_size);
*

where buf points to where the message is stored. PIPE_NAME can be NULL. It is passed verbatim to the receiver.

To wait for a message from the driver:

* void *msg;
* ...
* size = wimaxll_msg_read(wmx, PIPE_NAME, &msg);
*

Note this call is synchronous and blocking, and won't timeout. You can put it on a thread to emulate asynchrony (see Multithreading), but still it is quite difficult to integrate it in an event loop. Read on for mainloop integration options.

In msg you get a pointer to a dynamically allocated (by libwimaxll) area with the message payload. When the application is done processing the message, call:

*

All functions return negative errno codes on error.

To integrate message reception into a mainloop, callbacks and select() should be used. The file descriptor associated to the default message pipe can be obtained with wimaxll_recv_fd(). When there is activity on the file descriptor, wimaxll_recv() should be called:

* wimax_recv(wmx);
*

this will, as explained in Receiving notifications from the WiMAX kernel stack, for each received notification, execute its callback.

The callback for reception of messages from the WiMAX kernel stack can be set with wimaxll_set_cb_msg_to_user()). For detailed information on the message reception callback, see the definition of wimaxll_msg_to_user_cb_f.

Typedef Documentation

typedef int(* wimaxll_msg_to_user_cb_f)(struct wimaxll_handle *wmx, void *priv, const char *pipe_name, const void *data, size_t size)

Callback for a message to user generic netlink message.

A driver specific message has been received from the kernel; the pointer to the data and the size are passed in data and size. The callback can access that data, but it's lifetime is valid only while the callback is executing. If it will be accessed later, it has to be copied to a safe location.

Note
See Callbacks callbacks for a set of warnings and guidelines for using callbacks.
Parameters
wmxWiMAX device handle
privContext passed by the user with wimaxll_pipe_set_cb_msg_to_user().
pipe_nameName of the pipe the message is sent for
dataPointer to a buffer with the message data.
sizeSize of the buffer
Returns
>= 0 if it is ok to keep processing messages, -EBUSY if message processing should stop and control be returned to the caller. Any other negative error code to continue processing messages skipping the current one.

Function Documentation

void wimaxll_msg_free ( void *  msg)

Free a message received with wimaxll_msg_read()

Parameters
msgmessage pointer returned by wimaxll_msg_read().

Referenced by main().

ssize_t wimaxll_msg_read ( struct wimaxll_handle wmx,
const char *  pipe_name,
void **  buf 
)

Read a message from any WiMAX kernel-user pipe.

Parameters
wmxWiMAX device handle
pipe_nameName of the pipe for which we want to read a message. If NULL, only messages from the default pipe (without pipe name) will be received. To receive messages from any pipe, use pipe WIMAX_PIPE_ANY.
bufSomewhere where to store the pointer to the message data.
Returns
If successful, a positive (and *buf set) or zero size of the message; on error, a negative errno code (buf n/a).

Returns a message allocated in *buf as sent by the kernel via the indicated pipe. The message is allocated by the library and owned by the caller. When done, it has to be freed with wimaxll_msg_free() to release the space allocated to it.

Note
This is a blocking call.

Referenced by main().

ssize_t wimaxll_msg_write ( struct wimaxll_handle wmx,
const char *  pipe_name,
const void *  buf,
size_t  size 
)

Send a driver-specific message to a WiMAX device.

Parameters
wmxwimax device descriptor
pipe_nameName of the pipe for which to send the message; NULL means adding no destination pipe.
bufPointer to the message.
sizesize of the message.
Returns
0 if ok < 0 errno code on error. On error it is assumed the message wasn't delivered.

Sends a data buffer down to the kernel driver. The format of the message is driver specific.

Note
This is a blocking call

Referenced by i2400m_msg_to_dev().

int wimaxll_recv_fd ( struct wimaxll_handle wmx)

Return the file descriptor associated to a WiMAX handle.

Parameters
wmxWiMAX device handle
Returns
file descriptor associated to the handle can be fed to functions like select() to wait for notifications to be ready..

This allows to select() on the file descriptor, which will block until a message is available, that then can be read with wimaxll_recv().