SIM Manager Extended Phone Book Support

Article
04/07/2010

4/7/2010

Harish Srinivasan, Microsoft Corporation

September 2007

Summary

This paper discusses the new SIM Manager APIs that are present as part of Windows Mobile 6. Specifically, this paper will describe the new API structures and some sample code to use them.

Applies To

Microsoft Windows Mobile 6 Professional

Microsoft Windows Mobile 6 Standard

Microsoft Windows Embedded CE 6.0

Introduction

New Structures

Application Programming Interfaces (APIs)

Introduction

Telecommunications System (UMTS) network technologies included many changes to the Subscriber Identity Module (SIM) card. The new UMTS specifications created a new definition for Universal SIM (USIM) cards, and, while the general architecture of the USIM remained basically the same as a SIM, new functionality was added and some existing functionality was been changed or expanded. Primarily, the areas of CellCore that require changes for USIM are support for:

New and changed SIM files
Expanded SIM phonebook entries

CellCore exposes utility functions through ccoredrv.dll to allow for easy access to commonly used SIM files. Many of these files were not defined as a part of the original GSM specification but were defined by the Common PCN Handset Specification (CPHS), which is a commonly adopted requirement by operators. The USIM specification has taken the needs of the CPHS specification into account and has created new files with similar functionality (but different layouts from CPHS) within the USIM specification.

The following new USIM files (and file IDs) complement the existing CPHS files and require modifications to existing CellCore utility APIs:

Call Forwarding (0x6FCB)
Voice mail indications (0x6FCA)
Voice mail number (0x6FC7)
PLMN Network Name (0x6FC5)
Emergency calling code (changed from SIM to USIM)

The data that can be stored in the USIM phone book entry has also been enhanced. Previously, a SIM phone book entry only allowed the following information:

Name
Number
255 entries

New fields available for entries in the USIM phone book are:

Additional Name
Additional Numbers in definable categories (Mobile, Home, Office, and so on)
E-mail Addresses
Groups
Hidden entries
An large number of phone book entries (minimum 500)
Added information to aid synchronization

The expanded USIM phone book information is going to require changes to the phone book APIs and associated structures of the SIM Manager API—which is directly related to the read/write phone book AT commands (+CPBR, +CPBW) through the RIL_ReadPhonebookEntries and RIL_WritePhonebookEntry Radio Interface Layer (RIL) API functions. Currently these functions provide an easy-to-use way of accessing the phone book information stored in the abbreviated dialing numbers file (EF-adn), fixed dialing numbers file (EF-fdn), and so on. However, where the data that is able to be stored in the USIM phone book has been improved, the corresponding phone book AT commands have not been improved to handle the new information for ETSI specifications up to release 5. This means that to support the new USIM phone book information, the SIM Manager driver will need to be greatly modified to retrieve all the information directly from multiple USIM files rather than using existing AT commands and relying on the radio to form up the data from the SIM files. This will amount to making many calls to the Radio Interface Layer using the RIL_SendRestrictedSim API to access all the phone book entry data located in different USIM files.

Note For the complete list of the SIM files and their contents, please see 3GPP section 4.

The new USIM phone book specification also optionally provides information to aid in phone book synchronization. Where appropriate, synchronization information that applies to an individual entry will be provided as a part of the entry data. Currently, this only encompasses the unique ID that can be associated to a phone book entry. The other synchronization information is stored in transparent USIM files, and can be retrieved using existing APIs without modification, so synchronization is not directly addressed within this design specification and is more appropriate at a contact application level. For more information on USIM synchronization, please see 3GPP 31.102, section 4.4.2.12.

Microsoft Windows Mobile 6 now supports the extended phone book functionality for the USIM through new SIM Manager APIs. This paper describes in detail the functionality provided by each of these new APIs and how they can be used for working with a USIM.

It is important to note that both the old and new APIs will function with 2G and 3G SIMs. Existing clients can continue to use the old read/write functions to retrieve the name and number of both SIMs and USIMs. Clients using the new API can retrieve the name and number from 2G SIMs in addition to retrieving the full information available from a USIM. Below is a high-level chart of behavior:

Table 1

Existing API	Description
2G SIM	Read/Write name and number from EF-ADN to existing phone book data structure.
3G USIM	Read/Write name and number from DF-Telecom\DF-Phonebook to existing phone book data structure.
New API	Description
2G SIM	Read/Write only name and number from EF-ADN to new phone book data structure.
3G USIM	Read/Write full information from DF-Telecom\DF-Phonebook to new phone book data structure.

New Structures

SIMPHONEBOOKENTRYEX

The SIMPHONEBOOKENTRYEX structure supports a SIM phone book entry. This structure is part of the SIM Manager API set that enables access to information stored on the SIM card.

New additions as compared to the old SIMPHONEBOOKENTRY in bold:

typedef struct simphonebookentryex_tag {

DWORD cbSize;

DWORD dwParams;

TCHAR lpszAddress[MAX_LENGTH_ADDRESS];

DWORD dwAddressType;

DWORD dwNumPlan;

TCHAR lpszText[MAX_LENGTH_PHONEBOOKENTRYTEXT];

TCHAR lpszSecondName[MAX_LENGTH_PHONEBOOKENTRYTEXT];

DWORD dwIndex;

BOOL fHidden;

DWORD dwGroupIdCount;

DWORD rgdwGroupId[MAX_NUM_GROUPS];

DWORD dwUid;

DWORD dwAdditionalNumberCount;

LPSIMPHONEBOOKADDITIONALNUMBER* lpAdditionalNumbers;

DWORD dwEmailCount;

LPSIMPHONEBOOKEMAILADDRESS* lpEmailAddresses;

} SIMPHONEBOOKENTRYEX, *LPSIMPHONEBOOKENTRYEX;

Members

cbSize

Size of buffer in bytes. Must be set to sizeof(SIMPHONEBOOKENTRYEX) to provide for a versioning mechanism.

dwParams

Indicates valid parameter values in structure. See simmgr.h for a list of valid SIM_PARAM_PBEX_* values.

lpszAddress

A string containing the actual phone number.

Table 2

Constant	Value
MAX_LENGTH_ADDRESS	256

dwAddressType

A SIM_ADDRTYPE_* type representing the type number contained in lpszAddress.

Table 3

Value	Description
SIM_ADDRTYPE_UNKNOWN	Unknown.
SIM_ADDRTYPE_INTERNATIONAL	International number. Note The address should be prefixed with a "+" (plus sign), if not already, before being displayed to the user. Likewise, when writing an entry to the SIM, the address needs to be written correctly.
SIM_ADDRTYPE_NATIONAL	One national number.
SIM_ADDRTYPE_NETWKSPECIFIC	Network-specific number.
SIM_ADDRTYPE_SUBSCRIBER	Subscriber number (protocol-specific).
SIM_ADDRTYPE_ALPHANUM	Alphanumeric address.
SIM_ADDRTYPE_ABBREV	Abbreviated number.

dwNumPlan

A SIM_NUMPLAN_* type representing the number plan contained in lpszAddress.

Table 4

Value	Description
SIM_NUMPLAN_UNKNOWN	Unknown.
SIM_NUMPLAN_TELEPHONE	ISDN/telephone numbering plan (E.164/E.163).
SIM_NUMPLAN_DATA	Data numbering plan (X.121).
SIM_NUMPLAN_TELEX	Telex numbering plan.
SIM_NUMPLAN_NATIONAL	National numbering plan.
SIM_NUMPLAN_PRIVATE	Private numbering plan.
SIM_NUMPLAN_ERMES	ERMES numbering plan (ETSI DE/PS 3 01-3).

lpszText

A string for the text associated with the entry. Usually the name of the contact.

Table 5

Constant	Value
MAX_LENGTH_PHONEBOOKENTRYTEXT	256

lpszSecondName

A string for the second name associated with the entry. String array size is dwMaxSecondNameLength.

dwIndex

Specifies the index of the entry.

fHidden

Indicates if the entry is hidden or not.

dwGroupIdCount

Count of valid group IDs contained in rdwGroupId.

rdwGroupId

An array of group IDs associated with the entry.

Table 6

Constant	Value
MAX_NUM_GROUPS	10

dwUid

Unique identifier.

dwAdditionalNumberCount

Count of additional numbers in the lpAdditionalNumbers array.

lpAdditionalNumbers

Pointer to an array of SIMPHONEBOOKADDITIONALNUMBER structures. The maximum number of additional numbers is indicated by SIMPHONEBOOKCAPS.dwAdditionalNumberCount.

dwEmailCount

Number of e-mail addresses in the lpEmailAddresses array.

lpEmailAddresses

Pointer to an array of SIMPHONEBOOKEMAILADDRESS structures. The maximum number of email address is indicated by IMPHONEBOOKCAPS.dwEmailAddressCount.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Microsoft Windows CE 6.0

Header: simmgr.h

SIMPHONEBOOKADDITIONALNUMBER

The SIMPHONEBOOKADDITIONALNUMBER structure supports one of the possible additional number items, information about the type of number, and a link to possible further additional numbers associated with a phone book entry.

typedef struct simphonebookadditionalnumber_tag {
    DWORD cbSize;
    DWORD dwParams;
    TCHAR lpszAddress[MAX_LENGTH_ADDRESS];
    DWORD dwAddressType;                            
    DWORD dwNumPlan;
    DWORD dwNumId;
} SIMPHONEBOOKADDITIONALNUMBER, *LPSIMPHONEBOOKADDITIONALNUMBER;

Members

cbSize

Size of buffer in bytes. Must be set to sizeof(SIMPHONEBOOKADDITIONALNUMBER) to provide for a versioning mechanism.

dwParams

Indicates valid parameter values in structure. See simmgr.h for a list of valid SIM_PARAM_ADDITIONALNUM_* values.

lpszAddress

A string containing the actual phone number.

Table 7

Constant	Value
MAX_LENGTH_ADDRESS	256

dwAddressType

A SIM_ADDRTYPE_* type representing the type number contained in lpszAddress.

Table 8

Value	Description
SIM_ADDRTYPE_UNKNOWN	Unknown.
SIM_ADDRTYPE_INTERNATIONAL	International number. Note The address should be prefixed with a "+" (plus sign), if not already, before being displayed to the user. Likewise, when writing an entry to the SIM, the address needs to be written correctly.
SIM_ADDRTYPE_NATIONAL	One national number.
SIM_ADDRTYPE_NETWKSPECIFIC	Network-specific number.
SIM_ADDRTYPE_SUBSCRIBER	Subscriber number (protocol-specific).
SIM_ADDRTYPE_ALPHANUM	Alphanumeric address.
SIM_ADDRTYPE_ABBREV	Abbreviated number.

dwNumPlan

A SIM_NUMPLAN_* type representing the number plan contained in lpszAddress.

Table 9

Value	Description
SIM_NUMPLAN_UNKNOWN	Unknown.
SIM_NUMPLAN_TELEPHONE	ISDN/telephone numbering plan (E.164/E.163).
SIM_NUMPLAN_DATA	Data numbering plan (X.121).
SIM_NUMPLAN_TELEX	Telex numbering plan.
SIM_NUMPLAN_NATIONAL	National numbering plan.
SIM_NUMPLAN_PRIVATE	Private numbering plan.
SIM_NUMPLAN_ERMES	ERMES numbering plan (ETSI DE/PS 3 01-3).

dwNumId

Number identifier linking the number to a specific type. The number ID types can be retrieved using the SimReadPhonebookTag API.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

SIMPHONEBOOKEMAILADDRESS

The SIMPHONEBOOKEMAILADDRESS structure supports the details of one of the possible e-mail address items associated with a phone book entry.

typedef struct simphonebookemailaddress_tag {
    DWORD cbSize;
    DWORD dwParams;
    TCHAR lpszAddress[MAX_LENGTH_PHONEBOOKENTRYTEXT];
} SIMPHONEBOOKEMAILADDRESS, *LPSIMPHONEBOOKEMAILADDRESS;

Members

cbSize

Size of buffer in bytes. Must be set to sizeof(SIMPHONEBOOKEMAILADDRESS) to provide for a versioning mechanism.

dwParams

Indicates valid parameter values in structure. See simmgr.h for a list of valid SIM_PARAM_EMAIL_* values

lpszAddress

A string containing the e-mail address. For MAX_LENGTH_PHONEBOOKTEXT see SIMPHONEBOOKENTRYEX lpszText.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

SIMPHONEBOOKCAPS

The SIMPHONEBOOKCAPS structure addresses the various capabilities of the SIM phone book.

typedef struct simphonebookcaps_tag {
    DWORD cbSize;
    DWORD dwParams;
    DWORD dwStorages;
    DWORD dwMinIndex;
    DWORD dwMaxIndex;
    DWORD dwMaxAddressLength;
    DWORD dwMaxTextLength;
    DWORD dwMaxSecondNameLength;
    DWORD dwMaxAdditionalNumberLength;
    DWORD dwMaxEmailAddressLength;
    DWORD dwMaxGroupTagLength;
    DWORD dwMaxAdditionalNumberTagLength;
    DWORD dwAdditionalNumberCount;
    DWORD dwEmailAddressCount;
    DWORD dwMaxGroupTags;
    DWORD dwMaxAdditionalNumberTags;
    BOOL fHidden;
    BOOL fUid;
    DWORD dwMaxGroupIdCount;
} SIMPHONEBOOKCAPS, FAR *LPSIMPHONEBOOKCAPS;

Members

cbSize

Must be set to the sizeof(SIMPHONEBOOKCAPS) to provide a versioning mechanism.

dwParams

Indicates valid parameter values in structure. See simmgr.h for a list of valid SIM_PARAM_PBCAPS_* values.

dwStorages

Bit field of SIM_PBSTORAGE* values indicating supported storage locations. See simmgr.h for a list of SIM_PBSTORAGE_* values.

dwMinIndex

Lowest phone book entry index value.

dwMaxIndex

Highest phone book entry index value.

dwMaxAddressLength

Maximum length for the main number.

dwMaxTextLength

Maximum length for lpszText in bytes.

dwMaxSecondNameLength

Maximum length for the second name, in bytes.

dwMaxAdditionalNumberLength

Maximum length for additional numbers.

dwMaxEmailAddressLength

Maximum length for e-mail addresses, in bytes.

dwMaxGroupTagLength

Maximum length for group tag text, in bytes.

dwMaxAdditionalNumberTagLength

Maximum length for additional number tag text, in bytes.

dwAdditionalNumberCount

Number of supported additional numbers per entry.

dwEmailAddressCount

Number of supported e-mail addresses per entry.

dwMaxGroupTags

Total number of available group tags.

dwMaxAdditionalNumberTags

Total number of available additional number tags.

fHidden

Hidden flags support available.

fUid

Unique identifier available.

dwMaxGroupIdCount

Number of groups supported per entry.

Remarks

For all text, the lengths are in bytes. If the text needs to be saved in Unicode format, the max length can be calculated by (byteLength – 1)/2.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

Application Programming Interfaces (APIs)

SimReadPhonebookEntries()

The SimReadPhonebookEntries function reads a range of phone book entries from the SIM card. This function is part of the SIM Manager API set that enables access to information stored on the SIM card.

HRESULT SimReadPhonebookEntries(
    HSIM hSim,                             
    DWORD dwLocation,
    DWORD dwStartIndex,
    LPDWORD lpdwCount,
    LPDWORD lpdwBufferSize,
    LPSIMPHONEBOOKENTRYEX lpEntries
);

Parameters

hSim

Points to a valid HSIM handle.

dwLocation

A phone book storage location value; equal to one of the SIM_PBSTORAGE constant values.

dwStartIndex

Specifies the starting range index of phone book entries to retrieve.

lpdwCount

[in/out]

On input, the total number of contiguous indexes to check for valid entries starting from dwStartIndex. For example, a start index of 1 with a count of 5 will check indices 1–5 for valid entries.
On output (if the function succeeds), the actual number of SIMPHONEBOOKENTRYEX structures returned in lpEntries (empty entries are not returned).

lpdwBufferSize

[in/out]

On input, the number of bytes contained in the buffer pointed to by lpEntries.
On output, if the function fails and the error is SIM_E_BUFFERTOOSMALL, then it contains the minimum number of bytes to pass for the lpEntries parameter to retrieve the entries.

lpEntries

[out] Pointer to a block of memory, where SIM Manager can return an array of SIMPHONEBOOKENTRYEX structures and corresponding data on return. The returned structures are located consecutively at the head of the buffer. Variable-sized information referenced by pointers in the structures point to locations within the buffer located between the end of the SIMPHONEBOOKENTRYEX structure array and the end of the buffer.

Remarks

How large of a buffer is needed depends on the SIM phone book capabilities. Also when reading multiple entries, (for example, three entries), if the entries are interleaved (for example, entries valid in 1, 3, 7 but 2, 4, 5, 6 are empty), and if the dwStartIndex is 1, entries in 1, 3 will be retrieved and no entry will be retrieved for 2. The valid entries are stored contiguously in the lpEntries array; therefore, in this example, lpEntries[0] will contain entry 1 and lpEntries[1] will contain entry 3.

Return Values

HRESULT values are S_OK or one of the SIM_E errors. See SIM Manager Error Constants for the complete list of possible SIMM error codes.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

Library: cellcore.lib

Sample Code

HSIM hSim; // Valid SIM Handle obtained by a call to SimInitialize
DWORD dwAdditionalNumberCount; 
DWORD dwEmailAddressCount;
// Retrieve the values of dwAdditionalNumberCount and dwEmailAddressCount using the API SimGetPhonebookCapabilities
DWORD dwCount =2;
DWORD dwBufferSize =  (sizeof(SIMPHONEBOOKENTRYEX) +   dwAdditionalNumberCount*sizeof(SIMPHONEBOOKADDITIONALNUMBER)+
    dwEmailAddressCount*sizeof(SIMPHONEBOOKEMAILADDRESS)); 

// Now set the buffer size to the total struct size*number of entries to be read
dwBufferSize = dwBufferSize * dwCount;
DWORD dwLocation = SIM_PBSTORAGE_SIM;
DWORD dwStartIndex = 1;
LPSIMPHONEBOOKENTRYEX lpSimPBEx = (LPSIMPHONEBOOKENTRYEX)LocalAlloc(LPTR,dwBufferSize);
HRESULT hr = SimReadPhonebookEntries(hSim,dwLocation, dwStartIndex, &dwCount, lpSimPBEx,&dwBufferSize);

SimWritePhonebookEntryEx()

The SimWritePhonebookEntryEx writes a phone book entry to the SIM card. This function is part of the SIM Manager API set that enables access to information stored on the SIM card.

RESULT SimWritePhonebookEntryEx(
    HSIM hSim,                             
    DWORD dwLocation,
    DWORD dwIndex,
    LPSIMPHONEBOOKENTRYEX lpPhonebookEntry
);

Parameters

hSim

Points to a valid HSIM handle.

dwLocation

A phone book storage location cvalue; equal to one of the SIM_PBSTORAGE constant values.

dwIndex

Index number of the entry to write to the SIM; any existing entry at this location is overwritten. Set it to SIM_PBINDEX_FIRSTAVAILABLE (defined as 0xFFFFFFFF) if it does not matter to which index it is written. When this parameter is set to SIM_PBINDEX_FIRSTAVAILABLE, the resulting index value of the SIMCALLBACK function will also be set to SIM_PBINDEX_FIRSTAVAILABLE.

lpPhonebookEntry

[in] Points to a phone book entry structure. Only those fields indicated by the dwParams bitmask will be saved. Data corresponding to other fields not marked by the dwParams bitmask will not be altered on the SIM. This provides a way to update only changed values, rather than the needing to resave the entire entry.

Return Values

HRESULT values are S_OK or one of the SIM_E errors.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

Library: cellcore.lib

Sample Code

HSIM hSim; // Valid SIM Handle obtained by a call to SimInitialize
DWORD dwAdditionalNumberCount = 0xFFFFFFFF; 
DWORD dwEmailAddressCount = 0xFFFFFFFF;
SIMPHONEBOOKCAPS simPBCaps;
simPBCaps.cbSize = sizeof(simPBCaps);
simPBCaps.dwParams = SIM_PARAM_PBCAPS_ALL;

// Get the PB Capabilities
HRESULT hr = SimGetPhonebookCapabilities(hSim, & simPBCaps);
dwAdditionalNumberCount = simPBCaps.dwAdditionalNumberCount;
dwEmailAddressCount = simPBCaps.dwEmailAddressCount;
DWORD dwBufferSize = sizeof(SIMPHONEBOOKENTRYEX) +   dwAdditionalNumberCount*sizeof(SIMPHONEBOOKADDITIONALNUMBER)+
    dwEmailAddressCount*sizeof(SIMPHONEBOOKEMAILADDRESS);
DWORD dwCount =1;
DWORD dwLocation = SIM_PBSTORAGE_SIM;
DWORD dwIndex = SIM_PBINDEX_FIRSTAVAILABLE;
LPSIMPHONEBOOKENTRYEX lpSimPhonebookEntryEx= (LPSIMPHONEBOOKENTRYEX)LocalAlloc(LPTR,dwBufferSize);
// Do all the normal allocation checks here
 // set the numplan and addresstype params
 lpSimPhonebookEntryEx->dwNumPlan = SIM_NUMPLAN_TELEPHONE;
 lpSimPhonebookEntryEx->dwAddressType = SIM_ADDRTYPE_INTERNATIONAL;
lpSimPhonebookEntryEx->dwParams = SIM_PARAM_PBEX_ALL; // Assume all the Capabilities are supported by the USIM
_tcsncpy( lpSimPhonebookEntryEx->lpszAddress, _T("+14251111111"), simPBCaps.dwMaxAddressLength);
_tcsncpy( lpSimPhonebookEntryEx->lpszText , _T("Home Number"),simPBCaps.dwMaxTextLength);
_tcsncpy( lpSimPhonebookEntryEx->lpszSecondName,_T("Mobile Number"), simPBCaps. dwMaxSecondNameLength);


//Total storage space for  the entry must be allocated when the entry is created
//  Therefore, the maximum count of additional numbers and email addresses are allocated
//  even though only one is being populated at this time
lpSimPhonebookEntryEx->dwAdditionalNumberCount = simPBCaps.dwAdditionalNumberCount;
lpSimPhonebookEntryEx->lpAdditionalNumbers->dwAddressType = SIM_ADDRTYPE_INTERNATIONAL;
lpSimPhonebookEntryEx->lpAdditionalNumbers->dwNumPlan = SIM_NUMPLAN_TELEPHONE;
lpSimPhonebookEntryEx->lpAdditionalNumbers->dwParams = SIM_PARAM_ADDITIONALNUM_ALL;
// Populate one additional number and one email address only 
_tcsncpy( lpSimPhonebookEntryEx->lpAdditionalNumbers->lpszAddress , _T ("+14252222222"),simPBCaps.dwMaxAdditionalNumberLength);
// Set the dwNumID for the Additional Numbers
lpSimPhonebookEntryEx->lpAdditionalNumbers->dwNumId = 0x1;
// Email Address Data
  lpSimPhonebookEntryEx->dwEmailCount = simPBCaps.dwEmailAddressCount;
  lpSimPhonebookEntryEx->lpEmailAddresses->dwParams = SIM_PARAM_EMAIL_ALL;
_tcsncpy(lpSimPhonebookEntryEx->lpEmailAddresses->lpszAddress,_T("test@phone.com"), simPBCaps.dwMaxEmailAddressLength);
HRESULT hr = SimWritePhonebookEntryEx(hSim, dwLocation, dwIndex, lpSimPhonebookEntryEx);

SimGetPhonebookCapabilities()

The SimGetPhonebookCapabilities function provides the ability to query the capabilities of the SIM phone book. This function is a part of the SIM Manager API set that enables access to information stored on the SIM card.

HRESULT SimGetPhonebookCapabilities(
    HSIM hSim,                             
    LPSIMPHONEBOOKCAPS lpCapabilities
);

Parameters

hSim

Points to a valid HSIM handle.

lpCapabilities

SIM phone book capabilities structure. On input, set the dwParams bits according to the fields the information is requested for.

Return Values

HRESULT values are S_OK or one of the SIM_E errors.

Requirements

Windows Mobile: Windows Mobile 6 Classic and later

Windows Mobile 6 Professional and later

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

Library: cellcore.lib

Sample Code

HSIM hSim; // Valid SIM Handle obtained by a call to SimInitialize
SIMPHONEBOOKCAPS simPBCaps;
simPBCaps.cbSize = sizeof(simPBCaps);
simPBCaps.dwParams = SIM_PARAM_PBCAPS_ALL;
HRESULT hr = SimGetPhonebookCapabilities(hSim, &simPBCaps);
// Use the params in the simPBCaps structure
DWORD dwMaxAdditionalNumberLength = simPBCaps. dwMaxAdditionalNumberLength;
DWORD dwAdditionalNumberCount = simPBCaps. dwAdditionalNumberCount;

See SimWritePhonebookEntryEx sample code for an example of how to use the simPBCaps result structure.

SimReadPhonebookTag()

The SimReadPhonebookTag function reads the name value for a given index and tag (tag here refers to a friendly name such as “Mobile,” “Home,” “Office,” and so on).

HRESULT SimReadPhonebookTag(
    HSIM hSim,                             
    DWORD dwTag,
    DWORD dwIndex,
    LPTSTR szName,
    DWORD cchNameSize                       
);

Parameters

hSim

Points to a valid HSIM handle.

dwTag

A phone book tag value equal to one of the SIM_PBTAG constants.

Table 10

Value	Description
SIM_PBTAG_GROUP	Group information
SIM_PBTAG_NUMBER	Additional number types

dwIndex

Index of the tag to retrieve. One based index.

szName

[out] Buffer to contain the name of the tag.

cchNameSize

Size of destination buffer in characters.

Return Values

HRESULT values are S_OK or one of the SIM_E errors. If the size of szName is insufficient, SIM_E_BUFFERTOOSMALL will be returned. MAX_PATH is a safe value to use for a buffer size.

Requirements

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

Library: cellcore.lib

Sample Code

HSIM hSim; // Valid SIM Handle obtained by a call to SimInitialize
DWORD dwTag = SIM_PBTAG_NUMBER;
DWORD dwIndex = 1;
LPTSTR pszName;
DWORD cchNameSize = MAX_PATH;
pszName = (LPTSTR)LocalAlloc(LPTR,cchNameSize);
HRESULT hr = SimReadPhonebookTag(hSim, dwTag, dwIndex,pszName,cchNameSize);

SimWritePhonebookTag()

The SimWritePhonebookTag function writes the name value to a given tag(tag here refers to a friendly name such as “Mobile,” “Home,” “Office,” and so on) type and index.

HRESULT SimWritePhonebookTag(
    HSIM hSim,                             
    DWORD dwTag,
    DWORD dwIndex,
    LPTSTR szName
);

Parameters

hSim

Points to a valid HSIM handle.

dwTag

A phone book tag value equal to one of the SIM_PBTAG constants. See SimReadPhonebookTag for details.

dwIndex

Index of the tag to write to the SIM. One based index.

szName

[in] Buffer containing a string of the tag name to write.

Return Values

HRESULT values are S_OK or one of the SIM_E errors. See SIM Manager Error Constants for the list complete list of possible SIMM error codes.

Requirements

Windows Mobile 6 Standard and later

Operating System Versions: Windows CE 6.0

Header: simmgr.h

Library: cellcore.lib

Sample Code

HSIM hSim; // Valid SIM Handle obtained by a call to SimInitialize
DWORD dwTag = SIM_PBTAG_NUMBER;
DWORD dwIndex = 1;
TCHAR szName[MAX_LENGTH_PHONEBOOKENTRYTEXT] = _T("Mobile");
HRESULT hr = SimWritePhonebookTag(hSim,dwTag,dwIndex,szName);

Conclusion

For the latest information about Windows Mobile 6, see the Windows Mobile Web site at https://www.microsoft.com/windowsmobile/default.mspx.

SIM Manager Extended Phone Book Support

Summary

Applies To

Introduction

New Structures

SIMPHONEBOOKENTRYEX

Members

Requirements

SIMPHONEBOOKADDITIONALNUMBER

Members

Requirements

SIMPHONEBOOKEMAILADDRESS

Members

Requirements

SIMPHONEBOOKCAPS

Members

Remarks

Requirements

Application Programming Interfaces (APIs)

SimReadPhonebookEntries()

Parameters

Remarks

Return Values

Requirements

Sample Code

SimWritePhonebookEntryEx()

Parameters

Return Values

Requirements

Sample Code

SimGetPhonebookCapabilities()

Parameters

Return Values

Requirements

Sample Code

SimReadPhonebookTag()

Parameters

Return Values

Requirements

Sample Code

SimWritePhonebookTag()

Parameters

Return Values

Requirements

Sample Code

Conclusion

Additional resources