PrevNextUpHome SophiaFramework UNIVERSE 5.3
SFBAddrBook
Wrapper Class for the IAddrBook interface.
#include <SFBAddrBook.h.hpp>
class SFBAddrBook : public SFBBase;
SFMTYPEDEFWRAPPER(SFBAddrBook)

Inheritance diagram

 Inheritance diagram of SFBAddrBookClass

Version

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

Reference

BREW API IAddrBook

Memember

Public Functions
SFBAddrRecSmp CreateRec( AEEAddrCat category , AEEAddrField* items , SInt32 itemCount )
Create a new address record.
SFCError EnumCategoryInit( Void )
Initialize the enumeration of address record categories supported by the address book on the device.
SFCError EnumFieldsInfoInit( AEEAddrCat category )
Initialize the enumeration of the fields supported in the address book for a given category.
Bool EnumNextCategory( AEEAddrCat* category )
Enumerate the next address record category supported by the address book on the device.
Bool EnumNextFieldsInfo( AEEAddrFieldInfo* fieldInfo )
Enumerate the next field supported in this category.
SFBAddrRecSmp EnumNextRec( Void )
Enumerate the next record that matches the search criteria that has been specified during the previous call to SFBAddrBook::EnumRecInit().
SFCError EnumRecInit( AEEAddrCat category , AEEAddrFieldID fieldId , VoidPtr data , UInt16 dataSize )
Initialize the enumeration of records in the address book based on the specified search criteria.
SFCError EnumRecInit( AEEAddrCat category , AEEAddrFieldID fieldId , SFXBufferPtr data )
Initialize the enumeration of records in the address book based on the specified search criteria.
SFCError GetLastError( Void )
Return the error that has occurred with the most recent address book operation.
UInt16 GetNumRecs( Void )
Return a count of the number of address records present in this address book.
UInt32 GetProperties( Void )
Return the properties of this SFBAddrBook interface.
SFBAddrRecSmp GetRecByID( UInt16 id )
Retrieve pointer to the address record whose ID is specified.
static
SFBAddrBookSmp
NewInstance( SFCErrorPtr exception = null )
Create a new SFBAddrBook instance,
static
SFBAddrBookSmp
NewInstance( AEECLSID clsid = AEECLSID_ADDRBOOK , SFCErrorPtr exception = null )
Create a new SFBAddrBook instance,
SFCError RemoveAllRecs( Void )
Remove all records in a given address book.
Void SetProperties( UInt32 properties )
Set the properties of this SFBAddrBook 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.

SFBAddrBook::CreateRec
Create a new address record.
[ public ]
SFBAddrRecSmp CreateRec(
    AEEAddrCat category   // category to which this address belongs. AEE_ADDR_CAT_NONE indicates "don’t care". Using AEE_ADDR_CAT_NONE is not recomended because the device may return null, or add a new category, or add to an existing default category
    AEEAddrField* items   // array of field(s) for the new address record to be put into the address book
    SInt32 itemCount      // number of field(s) in the pItems array of fields 
);

Reference

BREW API IADDRBOOK_CreateRec


SFBAddrBook::EnumCategoryInit
Initialize the enumeration of address record categories supported by the address book on the device.
[ public ]
SFCError EnumCategoryInit(Void);

Reference

BREW API IADDRBOOK_EnumCategoryInit | SFBAddrBook::EnumNextCategory


SFBAddrBook::EnumFieldsInfoInit
Initialize the enumeration of the fields supported in the address book for a given category.
[ public ]
SFCError EnumFieldsInfoInit(
    AEEAddrCat category   // specifies the category for which the field support is to be enumerated. 
                          // if this parameter is set to AEE_ADDR_CAT_NONE, this function initializes the enumeration of all the fields supported for all categories
);

Reference

BREW API IADDRBOOK_EnumFieldsInfoInit | AEEAddrCat | SFBAddrBook::EnumNextFieldsInfo


SFBAddrBook::EnumNextCategory
Enumerate the next address record category supported by the address book on the device.
[ public ]
Bool EnumNextCategory(
    AEEAddrCat* category   // contains the category information
);

Description

The enumeration must have been initialized using SFBAddrBook::EnumCategoryInit before using this function.

Reference

BREW API IAddrBook_EnumNextCategory | AEEAddrCat | SFBAddrBook::EnumCategoryInit


SFBAddrBook::EnumNextFieldsInfo
Enumerate the next field supported in this category.
[ public ]
Bool EnumNextFieldsInfo(
    AEEAddrFieldInfo* fieldInfo   // on input, this must be a valid pointer to the AEEAddrFieldInfo structure.
                                  // if the return value is true, this parameter contains information about the next type of field supported in this category
);

Description

It returns information about the fields supported for the given category. The enumeration must have been initialized using SFBAddrBook::EnumFieldsInfoInit before using this function.

Reference

BREW API IADDRBOOK_EnumNextFieldsInfo | AEEAddrFieldInfo | SFBAddrBook::EnumFieldsInfoInit


SFBAddrBook::EnumNextRec
Enumerate the next record that matches the search criteria that has been specified during the previous call to SFBAddrBook::EnumRecInit().
[ public ]
SFBAddrRecSmp EnumNextRec(Void);

Description

The SFBAddrBook::EnumRecInit function must be called successfully before invoking this function.

Reference

BREW API IADDRBOOK_EnumNextRec | SFBAddrBook::EnumRecInit


SFBAddrBook::EnumRecInit
Initialize the enumeration of records in the address book based on the specified search criteria.
[ public ]
SFCError EnumRecInit(
    AEEAddrCat category      // category type to be matched.
                             // if this is set to AEE_ADDR_CAT_NONE, it is ignored
    AEEAddrFieldID fieldId   //AEEAddrFieldID to be matched. 
                             // if this is set to AEE_ADDRFIELD_NONE, it is ignored.
                             // before specifying a field here, it must be checked if the address book permits searching based on this field. 
                             // this can be done using the functions IADDRBOOK_EnumFieldsInfoInit() and IADDRBOOK_EnumNextFieldsInfo()
    VoidPtr data             // if non-null, pData specifies the actual data that must be matched.
                             // if null, it is ignored
    UInt16 dataSize          // specifies the sizeof(pData)
);
[ public ]
SFCError EnumRecInit(
    AEEAddrCat category      // category type to be matched.
                             // if this is set to AEE_ADDR_CAT_NONE, it is ignored
    AEEAddrFieldID fieldId   //AEEAddrFieldID to be matched. 
                             // if this is set to AEE_ADDRFIELD_NONE, it is ignored.
                             // before specifying a field here, it must be checked if the address book permits searching based on this field. 
                             // this can be done using the functions IADDRBOOK_EnumFieldsInfoInit() and IADDRBOOK_EnumNextFieldsInfo()
    SFXBufferPtr data        // if not null, matched data is specified.
                             // if null, failure
);

Description

After enumeration has been initialized, the SFBAddrBook::EnumNextRec function can be used to iterate through the records that match this search criteria.

Reference

BREW API IADDRBOOK_EnumRecInit | AEEAddrCat | AEEAddrFieldID | SFBAddrBook::EnumNextRec | SFBAddrBook::EnumFieldsInfoInit | SFBAddrBook::EnumNextFieldsInfo


SFBAddrBook::GetLastError
Return the error that has occurred with the most recent address book operation.
[ public ]
SFCError GetLastError(Void);

Reference

BREW API IADDRBOOK_GetLastError


SFBAddrBook::GetNumRecs
Return a count of the number of address records present in this address book.
[ public ]
UInt16 GetNumRecs(Void);

Reference

BREW API IADDRBOOK_GetNumRecs


SFBAddrBook::GetProperties
Return the properties of this SFBAddrBook interface.
[ public ]
UInt32 GetProperties(Void);

Version

Introduced BREW Client 2.1

Reference

BREW API IADDRBOOK_GetProperties | SFBAddrBook::SetProperties


SFBAddrBook::GetRecByID
Retrieve pointer to the address record whose ID is specified.
[ public ]
SFBAddrRecSmp GetRecByID(
    UInt16 id   // id of the record that needs to be retrieved from the address book
);

Description

The Record ID of a record can be obtained using SFBAddrRec::GetRecID.

Reference

BREW API IADDRBOOK_GetRecById | SFBAddrRec::GetRecID


SFBAddrBook::NewInstance
Create a new SFBAddrBook instance,
[ public, static ]
SFBAddrBookSmp NewInstance(
    SFCErrorPtr exception = null   // Error
);
[ public, static ]
SFBAddrBookSmp NewInstance(
    AEECLSID clsid = AEECLSID_ADDRBOOK   // Class ID
    SFCErrorPtr exception = null         // Error
);

Description

The parameter clsid is specified by the ClassID of IAddressBook interface. Only the AEECLSID_ADDRBOOK is avilable in BREW 2.0, In BREW 2.1, the AEECLSID_RUIM is also avilable.


SFBAddrBook::RemoveAllRecs
Remove all records in a given address book.
[ public ]
SFCError RemoveAllRecs(Void);

Description

Because this function has a huge impact on the address book, it may not be supported on all devices. If this function is not supported, the value EUNSUPPORTED is returned.

Reference

BREW API IADDRBOOK_RemoveAllRecs


SFBAddrBook::SetProperties
Set the properties of this SFBAddrBook interface.
[ public ]
Void SetProperties(
    UInt32 properties   // properties
);

Version

Introduced BREW Client 2.1

Reference

BREW API IADDRBOOK_SetProperties | SFBAddrBook::GetProperties