EPOC   SDK Home Glossary Indexes Previous Next Up

RGsmPhoneBook class


Contents


RGsmPhoneBook class — GSM phone book

Section Contents


Overview

Derivation

RTelSubSessionBase

Base class. Defines telephony sub-session.

Defined in

etelbgsm.h

Link against

gsmbas.lib

Description

Provides access to the functionality associated with a phone book.

Writing derived classes

This class is not intended for user derivation


Construction and destruction


RGsmPhoneBook() — Default C++ constructor

RGsmPhoneBook();

Description

The default C++ constructor constructs a phone book object.


RGsmPhoneBook() — Copy constructor

RGsmPhoneBook(const RGsmPhoneBook& aPhoneBook);

Description

The C++ copy constructor constructs a new RGsmPhoneBook object from an existing one.

Arguments

const RGsmPhoneBook& aPhoneBook

The phone book being copied.


Get phone book capability function


GetCaps() — Get phone book capabilities

TInt GetCaps(TCaps& aCaps) const;

Description

This function retrieves the phone book’s static capabilities.

Arguments

TCaps& aCaps

On return, contains the phone book’s static capabilities.

Return value

TInt

An error code: see System error codes.


Open and close phone book functions


Open() — Open phone book

TInt Open(RPhone& aPhone, const TDesC& aType);

Description

This function opens a specified phone book.

Arguments

RPhone& aPhone

The phone subsession in which the phone book is being opened.

const TDesC& aType

The name of the phone book to be opened. Known phone books are described in the “Existing phone book constants” section below.

Return value

TInt

An error code: see System error codes.


Close() — Close phone book

void Close();

Description

This function closes a phone book.


Phone book information functions


GetInfo() — Get phone book information — synchronous

TInt GetInfo(RBasicGsmPhone::TPhoneBookInfo& aInfo) const;

Description

This synchronous function retrieves a phone book’s information.

Arguments

RBasicGsmPhone::TPhoneBookInfo& aInfo

On return, contains information about the phone book.

Return value

TInt

An error code: see System error codes.


GetInfo() — Get phone book information — asynchronous

void GetInfo(TRequestStatus& aStatus, RBasicGsmPhone::TPhoneBookInfo& aInfo);

Description

This asynchronous function retrieves a phone book’s information.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

RBasicGsmPhone::TPhoneBookInfo& aInfo

On request completion, contains information about the phone book.


GetInfoCancel() — Cancel request to get phone book information

void GetInfoCancel() const;

Description

This function cancels an outstanding request to retrieve phone book information, placed with the asynchronous variant of the GetInfo() function.


Read phone book entry functions


Read() — Get phone book entry by index — synchronous

TInt Read(TEntry& aEntry);

Description

This synchronous function retrieves the phone book entry associated with the index specified in the TEntry structure.

Arguments

TEntry& aEntry

Phone book entry structure with the desired index specified in the iIndex member variable. On return, contains all the specified phone book entry information.

Return value

TInt

An error code: see System error codes.

Notes:

Read() — Get phone book entry by index — asynchronous

void Read(TRequestStatus& aStatus, TEntry& aEntry);

Description

This asynchronous function retrieves the phone book entry associated with the index specified in the TEntry structure.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TEntry& aEntry

Phone book entry structure with the desired index specified in the iIndex member variable. On return, contains all the specified phone book entry information.

Notes:

ReadCancel() — Cancel request to get phone book entry by index

void ReadCancel() const;

Description

This function cancels an outstanding phone book entry read request, placed using the asynchronous variant of the Read() function.


ReadFirst() — Get first phone book entry — synchronous

TInt ReadFirst(TEntry& aEntry);

Description

This synchronous function reads the entry in the first phone book slot.

Arguments

TEntry& aEntry

On return, contains the entry in the first phone book slot.

Return value

TInt

An error code: see System error codes.

Notes:

ReadFirst() — Get first phone book entry — asynchronous

void ReadFirst(TRequestStatus& aStatus, TEntry& aEntry);

Description

This asynchronous function reads the entry in the first phone book slot.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TEntry& aEntry

On request completion, contains the entry in the first phone book slot.

Notes:

ReadFirstCancel() — Cancel request to read the first phone book entry

void ReadFirstCancel() const;

Description

This function cancels a request to read the first phone book entry, placed using the asynchronous variant of the ReadFirst() function.


ReadPrevious() — Get previous phone book entry — synchronous

TInt ReadPrevious(TEntry& aEntry);

Description

This synchronous function retrieves the previous phone book entry. It should be preceded by at least one Read() function, to ensure the phone book cursor is greater than 1.

Arguments

TEntry& aEntry

On return, contains the previous entry — index one less than the last entry read.

Return value

TInt

An error code: see System error codes.


ReadPrevious() — Get previous phone book entry — asynchronous

void ReadPrevious(TRequestStatus& aStatus, TEntry& aEntry);

Description

This asynchronous function retrieves the previous phone book entry. It should be preceded by at least one Read() function, to ensure the phone book cursor is greater than 1.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TEntry& aEntry

On request completion, contains the previous entry — index one less than the last entry read.


ReadPreviousCancel() — Cancel request to get the previous phone book entry

void ReadPreviousCancel() const;

Description

This function cancels a request to read the previous phone book entry, placed using the asynchronous variant of the ReadPrevious() function.


ReadNext() — Get next phone book entry — synchronous

TInt ReadNext(TEntry& aEntry);

Description

This synchronous function retrieves the next phone book entry. It should be preceded by a Read() or ReadFirst() function, to ensure the phone book cursor is correctly positioned.

Arguments

TEntry& aEntry

On return, contains the next entry (index one more than the last entry read).

Return value

TInt

An error code: see System error codes.


ReadNext() — Get next phone book entry — asynchronous

void ReadNext(TRequestStatus& aStatus, TEntry& aEntry);

Description

This asynchronous function retrieves the next phone book entry. It should be preceded by a Read() or ReadFirst() function, to ensure the phone book cursor is correctly positioned.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TEntry& aEntry

On request completion, contains the next entry (index one more than the last entry read).


ReadNextCancel() — Cancel request to get the next phone book entry

void ReadNextCancel() const

Description

This function cancels a request to read the next phone book entry, placed using the asynchronous variant of the ReadNext() function.


Edit phone book entry functions


Write() — Write phone book entry — synchronous

TInt Write(TEntry& aEntry) const;

Description

This synchronous function writes an entry to the phone book.

Arguments

TEntry& aEntry

The entry to be written. The entry is written to the phone book slot specified by the aEntry.iIndex variable.

Return value

TInt

An error code: see System error codes.

Notes:

Write() — Write phone book entry — asynchronous

void Write(TRequestStatus& aStatus, TEntry& aEntry);

Description

This asynchronous function writes an entry to the phone book.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TEntry& aEntry

The entry to be written. The entry is written to the phone book slot specified by the aEntry.iIndex variable.

Notes:

WriteCancel() — Cancel request to write a phone entry

void WriteCancel() const;

Description

This function cancels an outstanding request to write a phone book entry, placed using the asynchronous variant of the Write() function.


Delete() — Delete phone book entry — synchronous

TInt Delete(TInt aIndex) const;

Description

This synchronous function is used to delete phone book entries.

Arguments

TInt aIndex

The index of the phone book entry that is to be deleted.

Return value

TInt

An error code: see System error codes.

Notes:

Delete() — Delete phone book entry — asynchronous

void Delete(TRequestStatus& aStatus, TInt aIndex);

Description

This asynchronous function is used to delete phone book entries.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TInt aIndex

The index of the phone book entry that is to be deleted.

Notes:

DeleteCancel() — Cancel request to delete phone book entry

void DeleteCancel() const;

Description

This function cancels an outstanding request to delete a phone book entry, placed using the asynchronous variant of the Delete() function.


Phone book entry change notification functions


EntryChangedNotification() — Notification of a change to a phone book entry

void EntryChangedNotification(TRequestStatus& aStatus,TInt& aIndex);

Description

This function provides notification when an entry in the phone book is modified.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.

TInt& aIndex

On request completion, contains the index number of the modified entry.


EntryChangedNotificationCancel() — Cancel notification of a change to a phone book entry

void EntryChangedNotificationCancel() const;

Description

This function cancels an asynchronous phone book entry change notification request, placed using the EntryChangedNotification() function.


Phone book search functions

The asynchronous phone book search functions are defined in the CGsmPhoneBookSearch and CGsmPhoneBookResults classes. It is recommended that developers use these, rather than the synchronous function (defined below), as the search may take some time.


SearchLC() — Phone book search — synchronous

CGsmPhoneBookResults* SearchLC(const TSearchString& aSearch);

Description

This synchronous function finds the search string in a phone book.

Arguments

const TSearchString& aSearch

The search string to be located. This is matched against the first letters in each entry.

Return value

CGsmPhoneBookResults*

On return, contains the results of the search.


Enumerations


Anonymous enum — Phone book write access capability flags

KCapsWriteAccess

New entries can be written to, or deleted from, the phone book.

KCapsRestrictedWriteAccess

New entries can only be written to, or deleted from, the phone book using the PIN2 password.

KCapsAddressChanged

The phone book supports notification functions. For example, it can inform clients when addresses have been added or removed.


Anonymous enum — Phone book entry size

KPhoneBookEntrySize

Max size of a phone book entry (100).


Struct


TCaps struct — Phone book capability information

TUint iCaps

Bitmask of the phone book capability flags — defined in the enumeration section.


Typdef


TSearchString typedef — Phone book entry search string

typedef TBuf8<KPhoneBookEntrySize> TSearchString;

Defined in

etelbgsm.h

Description

Objects of this type are used to pass search strings into phone book entry search functions.


Constants


Existing phone books

SIM_FIX_DIALLING_PHONEBOOK

A phone book containing the fixed SIM dialling list.

ME_PHONEBOOK

An ME-based phone book.

ME_AND_SIM_PHONEBOOK

A combination of ME and SIM-based phone books.

SIM_PHONEBOOK

A SIM-based phone book.

TA_PHONEBOOK

A TA-based phone book

LAST_DIALLED_PHONEBOOK

A phone book containing the most recently dialled calls, stored in either ME or SIM.

EMERGENCY_PHONEBOOK

A phone book containing the emergency number.

BARRED_PHONEBOOK

A phone book containing barred numbers.

MISSED_CALLS_PHONEBOOK

A phone book containing missed calls.

RECEIVED_CALLS_PHONEBOOK

A phone book containing received calls.

Notes:

RGsmPhoneBook::TEntry class — phone book entry information

Section Contents


Overview

Derivation

RGsmPhoneBook::TEntry

Scoped class. Defines structure of a phone book entry.

Defined in

etelbgsm.h

Link against

gsmbas.lib

Description

Provides data structure for containing the information belonging to a phone book entry.

Writing derived classes

This class is not intended for user derivation


Construction and destruction

The class does not declare a constructor.


Data members

TGsmTelNumber iTelNumber

A GSM Telephone number.

TBuf8<KPhoneBookEntrySize> iText

The name associated with the phone book entry. When writing to a phone book entry, the characters in this text string are mapped to characters in the 7-bit GSM character set.

TInt iIndex

The index number associated with the phone book entry.

TName iPhoneBookName

The name of the phone book.

EPOC       SDK Home Glossary Indexes Previous Next Up