Group PJ_SYMBIAN_OS

group PJ_SYMBIAN_OS

Functionalities specific to Symbian OS.

Symbian OS strongly discourages the use of polling since this wastes CPU power, and instead provides Active Object and Active Scheduler pattern to allow application (in this case, PJLIB) to register asynchronous tasks. PJLIB port for Symbian complies to this recommended behavior. As the result, few things have been changed in PJLIB for Symbian:

  • the timer heap (see Timer Heap Management.) is implemented with active object framework, and each timer entry registered to the timer heap will register an Active Object to the Active Scheduler. Because of this, polling the timer heap with pj_timer_heap_poll() is no longer necessary, and this function will just evaluate to nothing.

  • the ioqueue (see IOQueue: I/O Event Dispatching with Proactor Pattern) is also implemented with active object framework, with each asynchronous operation will register an Active Object to the Active Scheduler. Because of this, polling the ioqueue with pj_ioqueue_poll() is no longer necessary, and this function will just evaluate to nothing.

Since timer heap and ioqueue polling are no longer necessary, Symbian application can now poll for all events by calling User::WaitForAnyRequest() and CActiveScheduler::RunIfReady(). PJLIB provides a thin wrapper which calls these two functions, called pj_symbianos_poll().

Functions

pj_bool_t pj_symbianos_poll(int priority, int ms_timeout)

Wait the completion of any Symbian active objects. When the timeout value is not specified (the ms_timeout argument is -1), this function is a thin wrapper which calls User::WaitForAnyRequest() and CActiveScheduler::RunIfReady(). If the timeout value is specified, this function will schedule a timer entry to the timer heap (which is an Active Object), to limit the wait time for event occurences. Scheduling a timer entry is an expensive operation, therefore application should only specify a timeout value when it’s really necessary (for example, when it’s not sure there are other Active Objects currently running in the application).

Parameters

  • priority – The minimum priority of the Active Objects to poll, which values are from CActive::TPriority constants. If -1 is given, CActive::EPriorityStandard. priority will be used.

  • ms_timeout – Optional timeout to wait. Application should specify -1 to let the function wait indefinitely for any events.

Returns

PJ_TRUE if there have been any events executed during the polling. This function will only return PJ_FALSE if ms_timeout argument is specified (i.e. the value is not -1) and there was no event executed when the timeout timer elapsed.

pj_status_t pj_symbianos_set_params(pj_symbianos_params *prm)

Specify Symbian OS parameters to be used by PJLIB. This function MUST be called before pj_init() is called.

Parameters

prm – Symbian specific parameters.

Returns

PJ_SUCCESS if the parameters can be applied successfully.

void pj_symbianos_set_connection_status(pj_bool_t up)

Notify PJLIB that the access point connection has been down or unusable and PJLIB should not try to access the Symbian socket API (especially ones that send packets). Sending packet when RConnection is reconnected to different access point may cause the WaitForRequest() for the function to block indefinitely.

Parameters

up – If set to PJ_FALSE it will cause PJLIB to not try to access socket API, and error will be returned immediately instead.

struct pj_symbianos_params
#include <os.h>

This structure declares Symbian OS specific parameters that can be specified when calling pj_symbianos_set_params().