SwiApiNotify.c File Reference

Contains notifications API. More...

#include "SwiApiNotify.h"
#include "ap/apidefs.h"

Macros
#define	SWI_NOTIF_THREAD_TIMEOUT_MS   1000

Functions
SWI_API SWI_RCODE	SwiRegisterCallback (SWI_CALLBACK_EX pCallback, swi_uint64 nNotifications)
SWI_API SWI_RCODE	SwiDeRegisterCallback (SWI_CALLBACK_EX pCallback)
SWI_API SWI_RCODE	SwiNotify (enum SWI_TYPE_Notify eNotify, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiStopNotify (enum SWI_TYPE_Notify eNotify, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiCreateNotifThread (void(*threadfuncp)(void))
SWI_API SWI_RCODE	SwiWaitNotification (void)

Variables
swi_uint8	inbuf [APNTBUFSIZE]
struct SwiNotifyVariant	sNotifyVariant

Detailed Description

Contains notifications API.

Copyright: © 2011 Sierra Wireless, Inc. all rights reserved

Macro Definition Documentation

#define SWI_NOTIF_THREAD_TIMEOUT_MS   1000

Function Documentation

SWI_API SWI_RCODE SwiCreateNotifThread

(

void(*)(void)

threadfuncp

)

This function creates the Notification thread for the caller, blocking the caller until the thread creation is complete.

Parameters

threadfuncp

[IN] Pointer to the function serving as the thread's entry point

Returns

SWI_RCODE_OK - callback function successfully deregistered

SWI_RCODE_REQUEST_TIMEOUT - The request timed out meaning that the notification thread did not release the waiter in time

See Also

See SWI_RCODE for additional information.

SWI_API SWI_RCODE SwiDeRegisterCallback

(

SWI_CALLBACK_EX

pCallback

)

This function de-registers an application's callback handler.

After calling this function, notifications will no longer be passed to the specified callback handler.

Parameters

pCallback,:

[OUT] callback function pointer

Returns

SWI_RCODE_OK - callback function successfully deregistered

SWI_RCODE_INVALID_PAR - an invalid parameter was passed

See Also

See SWI_RCODE for additional information.

SWI_API SWI_RCODE SwiNotify	(	enum SWI_TYPE_Notify	eNotify,
		swi_uint32	timeout
	)

This function turns the notification ON for the specified event.

Calling this function enables event notifications to be routed to the callback handler registered earlier using SwiRegisterCallback. If notifications are enabled when there is no registered callback function, the API will silently discard them as they arrive. Similarly, if a filter were defined, notifications will be silently discarded.

Modem resets disable notifications (but leave the callback function registered). You must explicitly re-enable notifications if a modem reset is detected.

Once enabled, the modem will always send the current state of the notification object. When that notification is generated will depend on the object itself. After the initial indication, notifications are only generated when there is a change in state. Occasionally, notifications are generated at predefined intervals. See a description of the notification object for more information.

The following notifications are enabled by default and cannot be disabled:

SWI_NOTIFY_AirServerChange

All other notifications are disabled by default and must be enabled.

Parameters

eNotify,:	[IN] notification to enable
timeout,:	[IN] response timeout value in milliseconds

Returns

SWI_RCODE_OK - notification successfully enabled

SWI_RCODE_NOT_INIT - Notification thread has not been started.

See Also

See SWI_RCODE for additional information.

SWI_API SWI_RCODE SwiRegisterCallback	(	SWI_CALLBACK_EX	pCallback,
		swi_uint64	nNotifications
	)

This function registers a callback handler to receive event notifications.

All other notifications are disabled by default and must be enabled.

This release of the API supports multiple callback handlers. Notifications are sent to all registered callback handlers. Each callback function can provide a filter to mask out unwanted notifications on that particular callback function.

nNotifications should be set to 0xFFFFFFFFFFFFFFFF to receive all possible notifications.

Callback functions should be re-registered every time SwiSelectAirServer is called. This ensures that features of the newly bound device will have access to all the callback pointers.

On termination, SwiDeRegisterCallback should be called for each callback function previously registered.

This function must be called immediately after SwiApiOpen to ensure the client application receives critical events.

The following notifications are enabled by default and can not be disabled:

SWI_NOTIFY_AirServerChange

Parameters

pCallback,:	[OUT] callback function pointer
nNotifications,:	[IN] notification filter (see Notes)

See Also

See SWI_RCODE for additional information.

SWI_API SWI_RCODE SwiStopNotify	(	enum SWI_TYPE_Notify	eNotify,
		swi_uint32	timeout
	)

This function turns the notification OFF for the specified event.

After calling this function, the specified notifications will not be forwarded to the client's callback function.

The following notifications are enabled by default and can not be disabled:

SWI_NOTIFY_AirServerChange

Parameters

eNotify,:	[IN] notification to disable
timeout,:	[IN] response timeout value in milliseconds

See Also

See SWI_RCODE for additional information.

SWI_API SWI_RCODE SwiWaitNotification

(

void

)

The AP Notification receive API main entry point

When the received packet is wrong type the message "Wrong packet type" is logged and program terminates.

This function waits to receive notifications and invokes the user callback function if registered. This function does not return unless there is an error.

Returns

SWI_RCODE_OK - The function executed properly.

SWI_RCODE_FAILED - The function failed to execute correctly.

SWI_RCODE_API_NOT_OPEN - SDK is not running.

See Also

See SWI_RCODE for additional information.

Variable Documentation

swi_uint8 inbuf[APNTBUFSIZE]

struct SwiNotifyVariant sNotifyVariant