SlNetConn group

Managing and monitoring network connections. More...

Data Structures
struct	SlNetConn_config_t
	Global parameters and attributes used to establish connections. More...

Typedefs
typedef void(*	SlNetConn_AppEvent_f) (uint32_t ifID, SlNetConnStatus_e netStatus, void *data)
typedef struct SlNetConn_config_t	SlNetConn_config_t
	Global parameters and attributes used to establish connections. More...

Enumerations
enum	SlNetConnServiceLevel_e {   SLNETCONN_SERVICE_LVL_MAC = 0,   SLNETCONN_SERVICE_LVL_IP = 1,   SLNETCONN_SERVICE_LVL_INTERNET = 2 }
enum	SlNetConnStatus_e {   SLNETCONN_STATUS_DISCONNECTED = 1,   SLNETCONN_STATUS_WAITING_FOR_CONNECTION = 2,   SLNETCONN_STATUS_CONNECTED = 3,   SLNETCONN_STATUS_CONNECTED_MAC = SLNETCONN_STATUS_CONNECTED + SLNETCONN_SERVICE_LVL_MAC,   SLNETCONN_STATUS_CONNECTED_IP = SLNETCONN_STATUS_CONNECTED + SLNETCONN_SERVICE_LVL_IP,   SLNETCONN_STATUS_CONNECTED_INTERNET = SLNETCONN_STATUS_CONNECTED + SLNETCONN_SERVICE_LVL_INTERNET }

Functions
int32_t	SlNetConn_init (int32_t flags)
	Initialize the SlNetConn module. More...
int32_t	SlNetConn_setConfiguration (SlNetConn_config_t *pConf)
	Sets the SlNetConn global configuration parameters. More...
int32_t	SlNetConn_start (SlNetConnServiceLevel_e targetServiceLevel, SlNetConn_AppEvent_f fAppEventHdl, uint32_t timeout, uint32_t flags)
	Request a connection (of specific target level) to be establish. More...
int32_t	SlNetConn_stop (SlNetConn_AppEvent_f fAppEventHdl)
	Remove user's connection request. More...
int32_t	SlNetConn_waitForConnection (SlNetConnServiceLevel_e targetServiceLevel, uint32_t timeout)
	Wait for connection (of specific target level) to be establish. More...
int32_t	SlNetConn_getStatus (bool bCheckInternetConnection, SlNetConnStatus_e *pStatus)
	Retrieve the current connection status. More...
void *	SlNetConn_process (void *pvParameters)
	SlNetConn_process callback - Connection manager thread, handles all connection requests. More...

Detailed Description

Managing and monitoring network connections.

Typedef Documentation

SlNetConn_AppEvent_f

typedef void(* SlNetConn_AppEvent_f) (uint32_t ifID, SlNetConnStatus_e netStatus, void *data)

Application callback function prototype.

This function is per application and is called by the connection manager when an event occurs after the connection is established.

See also

SlNetConn_start(), SlNetConn_stop()

SlNetConn_config_t

typedef struct SlNetConn_config_t SlNetConn_config_t

Global parameters and attributes used to establish connections.

This structure is set using the SlNetConn_setConfiguration(). If the function is not called the default values will apply.

See also

SlNetConn_setConfiguration()

Enumeration Type Documentation

SlNetConnServiceLevel_e

enum SlNetConnServiceLevel_e

Enumerator
SLNETCONN_SERVICE_LVL_MAC
SLNETCONN_SERVICE_LVL_IP
SLNETCONN_SERVICE_LVL_INTERNET

SlNetConnStatus_e

enum SlNetConnStatus_e

Enumerator
SLNETCONN_STATUS_DISCONNECTED
SLNETCONN_STATUS_WAITING_FOR_CONNECTION
SLNETCONN_STATUS_CONNECTED
SLNETCONN_STATUS_CONNECTED_MAC
SLNETCONN_STATUS_CONNECTED_IP
SLNETCONN_STATUS_CONNECTED_INTERNET

Function Documentation

SlNetConn_init()

int32_t SlNetConn_init

(

int32_t

flags

)

Initialize the SlNetConn module.

SlNetConn_init() initializes the SlNetConn module. Internally, this includes:

• Allocating a connection manager CB
• Registering a SlNetIf events handler
• Creating a message queue to handle requests between the application and connection manager threads

This function is called by the application layer and can be called only once

Parameters

[in]

flags

Reserved

Returns

Zero on success, negative error code on failure

SlNetConn_setConfiguration()

int32_t SlNetConn_setConfiguration

(

SlNetConn_config_t *

pConf

)

Sets the SlNetConn global configuration parameters.

The use of this function is optional. If not called, SlNetConn will use the default configuration.

SlNetConn_setConfiguration() can only be called after SlNetConn_init() and before SlNetConn_start().

Parameters

[in]

pConf

SlNetConn configuration (see SlNetConn_config_t)

Returns

Zero on success, negative error code on failure

SlNetConn_start()

int32_t SlNetConn_start	(	SlNetConnServiceLevel_e	targetServiceLevel,
		SlNetConn_AppEvent_f	fAppEventHdl,
		uint32_t	timeout,
		uint32_t	flags
	)

Request a connection (of specific target level) to be establish.

SlNetConn_start() passes the connection manager a request to start a connection.

The connection request is valid until SlNetConn_stop() is called.

The fAppEventHdl identifies the request (same "fAppEventHdl" should be used in the SlNetConn_stop()).

The function is blocking (with timeout) until the requested connection is established or until the timeout expires (if timeout is 0, the function will return immediately). Timeout expiration doesn't cancel the request. The Start Connection handles temporary disconnections ("link down"). The user will get a "Disconnection" indication through the fAppEventHdl, but the connection is expected to re-established automatically (when possible). Following the return of the function, the user will be notified through the event handler on the "Connection" and "Disconnection" events. Upon disconnection, the user may use SlNetConn_waitForConnection() to block the execution until the link is up again.

This function can be called from several threads.

This function must be called after SlNetConn_init() and SlNetConn_setConfiguration().

Parameters

[in]	targetServiceLevel	Specifies the requested connection level
[in]	fAppEventHdl	Pointer to user callback function. A unique callback should be used per SlNetConn_start() request. The callback identifies the user request and should be used upon SlNetConn_stop().
[in]	timeout	Is an upper bound (in seconds) for the time the SlNetConn_start() can be blocked. 0 means non-blocking command - The command will return immediately. Value above 0xffff seconds mean infinity timeout.
[in]	flags	reserved

Returns

0 on success (i.e. connected with the requested service level), 1 when connection is still in process, or negative error code on failure. return code of '1' will occur when the timeout (even when timeout == 0) expires. It is not considered a failure. The connection indication (and any other status change) will be notified through fAppEventHdl. Since the request is still active, user may call SlNetConn_stop() in this case. Any (negative) error code means the Start request has failed.

See also

SlNetConn_stop()

SlNetConn_stop()

int32_t SlNetConn_stop

(

SlNetConn_AppEvent_f

fAppEventHdl

)

Remove user's connection request.

SlNetConn_stop() cancels a connection request (identified by user event handler). When the last user request is being removed, a disconnection will be triggered. This function is non-blocking and called by the application layer. This function must be called after SlNetConn_init() and SlNetConn_setConfiguration().

Parameters

[in]

fAppEventHdl

Pointer to user callback function. This should be a unique Callback pointer that corresponds to specific SlNetConn_start() request.

Returns

Zero on success, or negative error code on failure

See also

SlNetConn_start()

SlNetConn_waitForConnection()

int32_t SlNetConn_waitForConnection	(	SlNetConnServiceLevel_e	targetServiceLevel,
		uint32_t	timeout
	)

Wait for connection (of specific target level) to be establish.

SlNetConn_waitForConnection() waits until the requested connection is established. The function doesn't change user requests status and doesn't trigger a connection. It must follow a SlNetConn_start() with similar (or higher) target service level. This function is blocking. This function can be called from several threads. This function must be called after SlNetConn_init() and SlNetConn_setConfiguration().

Parameters

[in]	targetServiceLevel	Specifies the requested connection level
[in]	timeout	Is an upper bound (in seconds) for the time the SlNetConn_waitForConnection() can be blocked. 0 means non-blocking command. The command will return immediately. The return code can still be '1' (i.e. Timeout), if the connection setup is in progress. Value above 0xffff seconds mean infinity timeout.

Returns

0 on success (i.e. connected with the requested service level), 1 when connection is still in process, or negative error code on failure. This will occur when the timeout (even when timeout == 0) expires. Any (negative) error code means the Start request has failed.

SlNetConn_getStatus()

int32_t SlNetConn_getStatus	(	bool	bCheckInternetConnection,
		SlNetConnStatus_e *	pStatus
	)

Retrieve the current connection status.

This will be used by the user poll the current status of the connection manager. If an IP level of connection is already established, the bCheckInternetConnection can be set to request the SlNetConn to check whether an internet access is available.

Parameters

[in]	bCheckInternetConnection	Perform internet connection (if IP Address is Acquired) before reporting the active service level.
[out]	pStatus	The current active service level

Returns

Zero on success, or negative error code on failure

SlNetConn_process()

void* SlNetConn_process

(

void *

pvParameters

)

SlNetConn_process callback - Connection manager thread, handles all connection requests.

This is the main thread context of the SlNetConn, it will be used to process SlNetIf events and to invoke application's callbacks.

Parameters

[in]

pvParameters

Task parameters (should be kept null).

The thread (that uses this function) needs to be created by the application before SlNetConn_start() is called.