SFBAlarmMgr

Wrapper Class for the IAlarmMgr interface.

#include <SFBAlarmMgr.h.hpp>

class SFBAlarmMgr : public SFBQuery;

SFMTYPEDEFWRAPPER(SFBAlarmMgr)

Inheritance diagram

Version

BREW 2.0	BREW 2.1	BREW 3.1	BREW 4.0
X	X	O	O

Reference

BREW API IAlarmMgr

Member

Public Functions
`SFCError`	AlarmsActive( `AEECLSID` clsid ) Return SUCCESS if an alarm is set for the application specified by the class ID passed to the function.
`SFCError`	CancelAlarm( `AEECLSID` clsid , `UInt16` usercode ) Cancel an alarm set through SFBALARMMGR::SetAlarm()/SFBSHELL::SetAlarm().
`UInt16`	GetUserCode( `UInt32` usercode ) Get the user code.
`Bool`	IsCodeReserved( `UInt16` usercode ) Check if the specified user code is reserved by the calling application.
`SFCError`	ListAlarmCodes( `AEECLSID` clsid , `UInt16Ptr` usercodes , `UInt32Ptr` count ) This function works in two modes - either to list reserved user codes (list mode) or to query if the specified user code is reserved (query mode). In list mode this function lists all the user codes reserved for the application regardless of whether or not that alarm is active.
static `SFBAlarmMgrSmp`	NewInstance( `SFCErrorPtr` exception = null ) Create a new SFBAlarmMgr instance.
static `SFBAlarmMgrSmp`	NewInstance( `AEECLSID` id , `SFCErrorPtr` exception = null ) Create a new SFBAlarmMgr instance.
`SFCError`	ReserveUserCodes( `AEECLSID` clsid , `UInt16Ptr` usercodes , `UInt32Ptr` count ) Reserve the specified number of alarm codes for the application class ID specified without needing the application to actually set alarms.
`SFCError`	ResumeAlarms( `Void` ) This function allows the caller to resume operation of the BREW alarms subsystem.
`SFCError`	SetAlarm( `AEECLSID` clsid , `UInt32Ptr` usercode , `UInt32` seconds ) This function allows the caller to set a long-term alarm for an applet.
`UInt32`	SetUserCode( `UInt16` usercode , `Bool` provided , `Bool` absolute ) Set the user code.
`SFCError`	SuspendAlarms( `void` ) This function allows the caller to suspend operation of the BREW alarms subsystem.
`SFCError`	QueryInterface( `AEECLSID` clsid , `VoidHandle` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFCError`	QueryInterface( `AEECLSID` clsid , `SFBBaseSmpPtr` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFBBaseSmp`	QueryInterface( `AEECLSID` clsid ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`Void`	Self( `AEECLSID` clsidReq , `SFBQuerySmpPtr` clone , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.
`SFBQuerySmp`	Self( `AEECLSID` clsidReq , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.

Protected Functions
static `SFBBaseSmp`	FactoryByCreate( `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface.
static `SFBBaseSmp`	FactoryByQuery( `SFBQuerySmpConstRef` query , `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface using the SFBQuery instance.

SFBAlarmMgr::AlarmsActive

Return SUCCESS if an alarm is set for the application specified by the class ID passed to the function.

[ public ]
SFCError AlarmsActive(
    AEECLSID clsid   // The class ID whose alarms are checked for being active
);

Return value

SUCCESS: if there are pending alarms
ENOSUCH: if there are no pending alarms
EPRIVLEVEL: user does not have privilege level for the operation.
EBADPARM: invalid class ID.

Description

This function returns SUCCESS if an alarm is set for the application specified by the class ID passed to the function. If the class ID is zero, the function returns the result for the current running app. if classID is non-zero and not current app, the caller should have a privilege level of AEEGROUPID_ALARM_ALL.

Reference

BREW API IALARMMGR_AlarmsActive

SFBAlarmMgr::CancelAlarm

Cancel an alarm set through SFBALARMMGR::SetAlarm()/SFBSHELL::SetAlarm().

[ public ]
SFCError CancelAlarm(
    AEECLSID clsid    //  Applet class of alarm to cancel. 
    UInt16 usercode   // 16-bit use code of alarm to cancel. 
);

Return value

<listitem>SUCCESS: if an alarm is found and canceled. </listitem> <listitem>EFAILED: if an alarm cannot be found or canceled. </listitem> <listitem>EPRIVLEVEL: user does not have privilege level for the operation. </listitem> <listitem>EBADPARM: invalid class ID. </listitem>

Description

This function cancels an alarm set through IALARMMGR_SetAlarm()/ISHELL_SetAlarm(). The proper class and 16-bit user code must be specified. If the class ID is zero, the function returns the result for the current running app. If classID is non-zero and not current app, the caller should have a privilege level of AEEGROUPID_ALARM_ALL.

Reference

BREW API IALARMMGR_CancelAlarm

SFBAlarmMgr::GetUserCode

Get the user code.

[ public ]
UInt16 GetUserCode(
    UInt32 usercode   // user code
);

Reference

SFBAlarmMgr::SetUserCode

SFBAlarmMgr::IsCodeReserved

Check if the specified user code is reserved by the calling application.

[ public ]
Bool IsCodeReserved(
    UInt16 usercode   // The alarm user code checked if being reserved. 
);

Return value

TRUE: if alarm user code is reserved by the app.
FALSE: if alarm user code is not reserved by the app.

Reference

BREW API IALARMMGR_IsCodeReserved

SFBAlarmMgr::ListAlarmCodes

This function works in two modes - either to list reserved user codes (list mode) or to query if the specified user code is reserved (query mode). In list mode this function lists all the user codes reserved for the application regardless of whether or not that alarm is active.

[ public ]
SFCError ListAlarmCodes(
    AEECLSID clsid        // The class whose reserved alarm user codes are queried or are to be listed. 
    UInt16Ptr usercodes   // user code
    UInt32Ptr count       // the total number of reserved user codes
);

Argument

clsid: The class whose reserved alarm user codes are queried or are to be listed.
usercodes: Null on IN: pnCount contains number of reserved alarm user codes on out. Valid on IN: if pnCount not null - max pnCount number of alarm codes reserved are returned in it. Valid on IN: if pnCount null - the alarm user code is used to query if it is reserved. Value unchanged on OUT.
count: Null on IN: alarm user code specified in pnUserCode is queried if reserved. Valid on IN: specifies the max number of alarm user codes to return. On OUT has the total number of reserved user codes if pnUserCode is null.

Return value

SUCCESS: If able to query the number of number of Codes. pnUserCodes and pnCount will be updated if non-NULL.
EPRIVLEVEL: user does not have privilege level for the operation.

Description

In list mode this function lists all the user codes reserved for the application regardless of whether or not that alarm is active. If the class ID is zero, the function returns the result for the current running app. If classID is non-zero and not current app, the caller should have a privilege level of AEEGROUPID_ALARM_ALL.

Reference

BREW API IALARMMGR_ListAlarmCodes

SFBAlarmMgr::NewInstance

Create a new SFBAlarmMgr instance.

[ public, static ]
SFBAlarmMgrSmp NewInstance(
    SFCErrorPtr exception = null   // Error
);

[ public, static ]
SFBAlarmMgrSmp NewInstance(
    AEECLSID id                    // Class ID
    SFCErrorPtr exception = null   // Error
);

SFBAlarmMgr::ReserveUserCodes

Reserve the specified number of alarm codes for the application class ID specified without needing the application to actually set alarms.

[ public ]
SFCError ReserveUserCodes(
    AEECLSID clsid        // The class for which the alarm codes are to be reserved. 
    UInt16Ptr usercodes   // user codes
    UInt32Ptr count       // the number of user codes
);

Argument

clsid: The class for which the alarm codes are to be reserved.
usercodes: Contains the generated user codes on function return. It is the callers responsibility to allocate memory to contain nCount number of user codes. Deallocation is also the callers responsibility.
count: On IN specifies the number of user codes needed. On OUT specifies the number of user codes generated and returned.

Return value

SUCCESS: if alarm user code reservation was successful.
EFAILED: if alarm user code reservation failed.
EPRIVLEVEL: user does not have privilege level for the operation.
ENOTALLOWED: app does not have the privilege (AEEGROUPID_RESERVECODE_LARGE) to reserve specified number of user codes.

Description

un-used alarm codes for an application are released when it is deleted. If the class ID is zero, the function returns the result for the current running app. If classID is non-zero and not current app, the caller should have a privilege level of AEEGROUPID_ALARM_ALL. If an app wants to reserve more than 30 user codes it needs to have a privilege level of AEEGROUPID_RESERVECODE_LARGE.

Reference

BREW API IALARMMGR_ReserveUserCodes

SFBAlarmMgr::ResumeAlarms

This function allows the caller to resume operation of the BREW alarms subsystem.

[ public ]
SFCError ResumeAlarms(Void);

Return value

SUCCESS: if successful.
EPRIVLEVEL: insufficient privilege (must have AEEGROUPID_ALARM_MGR)
Other: AEEError if appropriate

Description

Any alarms that have already come due passed will be scheduled for notification. To resume alarms an application needs to have AEEGROUPID_ALARM_MGR privilege level.

Reference

BREW API IALARMMGR_ResumeAlarms SFBAlarmMgr::SuspendAlarms

SFBAlarmMgr::SetAlarm

This function allows the caller to set a long-term alarm for an applet.

[ public ]
SFCError SetAlarm(
    AEECLSID clsid       // Applet class to call when the alarm expires. 
    UInt32Ptr usercode   // pointer in which the generated 16-bit alarm user code is returned to/from the caller of API in the first 2 most significant bytes. 
    UInt32 seconds       // Number of seconds 
);

Argument

clsid: Applet class to call when the alarm expires.
usercode: pointer in which the generated 16-bit alarm user code is returned to/from the caller of API in the first 2 most significant bytes. The next 2 bytes are used as 16 bit flags. bit 1 if set specifies that user is supplied by user (else generated by BREW), bit 2 if set specifies that alarm seconds are for absolute time (else relative from now).
seconds: Number of seconds (relative from now or absolute) to set the alarm for.

Return value

SUCCESS: if successful.
EBADPARM: invalid parameter.
ENOMEMORY: insufficient memory.
ENORESOURCE: no free user code available.
EPRIVLEVEL: user does not have privilege level for the operation.

Reference

BREW API IALARMMGR_SetAlarm

SFBAlarmMgr::SetUserCode

Set the user code.

[ public ]
UInt32 SetUserCode(
    UInt16 usercode   // user code
    Bool provided     // if it is user provided
    Bool absolute     // absolute time of alarm
);

Reference

SFBAlarmMgr::GetUserCode

SFBAlarmMgr::SuspendAlarms

This function allows the caller to suspend operation of the BREW alarms subsystem.

[ public ]
SFCError SuspendAlarms(
    void    // 
);

Return value

SUCCESS: if successful.
EPRIVLEVEL: insufficient privilege (must have AEEGROUPID_ALARM_MGR)
Other: AEEError if appropriate

Description

This function does not impact applications' ability to schedule alarms, it merely postpones any alarm notifications until SFBALARMMGR::ResumeAlarms() is called, or the phone is reset. To suspend alarms an application needs to have AEEGROUPID_ALARM_MGR privilege level.

Reference

BREW API IALARMMGR_SuspendAlarms SFBAlarmMgr::ResumeAlarms