This chapter discusses various new API features that have been added in recent versions of the Nokia 9000i Communicator.
1 Software Version Number
2 User's Name
3 IMEI Code Number
4 New SMS Header
5 New Standard Monikers, Bitmaps
6 Non-exclusive Lists
7 Incremental Searches
8 Contact's URL and Password
9 ContactList Searches
10 Unknown Phone Numbers
The INI file contains the version number. The [ui] category's productName field will be one of the following strings:
There is also a software serial number, in the swSerialNumber field. This field has the format: 000000/00/AAABBCCDDLLLFKK/0
Use one of the the
IniFileReadString...()
routines to find out the value of these INI file fields.
Code Display 13-1 Getting the Software Version Number
@start StringRes; @chunk TCHAR UICategory[] = "ui"; @chunk TCHAR SWSerialNumber[] = "swSerialNumber"; @end StringRes;
...
@method TestProcessClass, MSG_TEST_PROCESS_GET_VERSION
{
TCHAR version[28] = "";
TCHAR *category;
TCHAR *key;
word value;
MemLock( OptrToHandle( @UICategory ) );
category = (TCHAR *) LMemDeref( @UICategory );
key = (TCHAR *) LMemDeref( @SWSerialNumber );
/*
* Extract the information you want from version string.
*/
MemUnlock( OptrToHandle( @UICategory ) ); }
The ContDB library has a new function,
ContactGetUserName()
, which returns the user's name.
To read the phone's IMEI number, you will need to use the
EciImeiGet()
function, provided by the eci library. This function takes one parameter, a pointer to a buffer to fill with the code number string. The buffer must be at least 17 bytes long, to hold the null-terminated 16-character code string. The function returns zero if the IMEI code was read succesfully, non-zero otherwise.
Code Display 13-2 Reading the IMEI Code
@include <eci.goh>
...
@method TestProcessClass, MSG_TEST_PROCESS_GET_IMEI
{
TCHAR imei[17] = "";
if ( EciGetImei( imei) == 0)
{
/*
* We got IMEI code, do any check you want.
*/
}
else
{
/*
* For some reason query failed.
*/
}
}
In addition to the old way to send messages to application using their
GeodeToken
in front of the actual data, a new user data header is now introduced. Otherwise sending and receiving messages has not changed. The new header adopts the concept from Narrow Band Socket specification.
The new header format is //SCKddoo or //SCKLddddoooo where dd (and dddd) represent "destination port" and oo (and oooo) represent "originator port". Both these headers are terminated with space character.These ports are ascii coded hexadecimal numbers.
Short header covers ports from 0 to 255 (00 to FF in hex) and the longer form from 0 to 65535 (0000 to FFFF in hex).
The range of port numbers is divided to reserved port address range and to dynamic and/or private port address range. Usage of port address range 0 to 49151 is restricted and assignment of a port in this range requires contacting port address assignment authority. The reserved port address range is further divided to ports for "well-known protocols" (range 0 to 239 and 256 to 1024) and to registered ports (range 1025 to 49151). Nokia has reserved ports 5500 to 5599 for company-specific protocols. Port addresses in the dynamic address range 240 to 255 or in the dynamic and/or private address range 49152 to 65535 may be used freely by any vendor.
In order to receive these messages application must register themselves to SMS receive application. This can be done using smreg library. This library offers functions for registering and unregistering.
SMRegRegisterApplication()
takes there parameters:
GeodeToken
of your application, a pointer to buffer containing "port numbers" you register for and number of messages you are registering. Port numbers must be ASCII coded hexadecimal numbers.
Code Display 13-3 Registering to receive "destination port" SMS Messages
@method TestProcessClass, MSG_TEST_PROCESS_REGISTER
{
GeodeToken appl;
TCHAR messageProtocol[5];
word protocol;
/* We register ourselves to listen port 43962 that is ABBA in hex. */
protocol = 43962;
appl.GT_chars[0] = `T';
appl.GT_chars[1] = `E';
appl.GT_chars[2] = `S';
appl.GT_chars[3] = `T';
appl.GT_manufID = 11;
/* Let's ask smreg library to convert 43962 to ascii coded hex for us. */
SMRegIntegerToHex( protocol, messageProtocol,
SMRITH_NULL_TERMINATE |SMRITH_WORD_LENGTH);
/* Now we have messageProtocol = "ABBA" */
SMRegRegisterApplication( appl, messageProtocol, 1);
}
You can register more than one port by calling the function:
SMRegRegisterApplication( appl, "ABBADADA0055", 3);
Then you will receive messages ABBA, DADA and 55.
The function returns a
SMRegResult
value: SMRR_OK if your registration was succesful; otherwise it will be SMRR_FAIL.
SMRegIntegerToHex()
function converts passed decimal integers to ascii coded hexadecimal strings. You pass a word containing integer to be converted, a character pointer where the result is stored and flags how the conversion is done. You can convert either byte length integers i.e. 0 to 255 and the result is two characters to word length i.e. 0 to 65535 and the result is four characters. By default the destination string is not null terminated, but if you pass flag SMRITH_NULL_TERMINATE null is added at the end of the string.
If you want to stop receiving messages you can unregister yourself. This can be done using
SMRegUnregisterApplication()
function. The parameters are identical to SMRegRegisterApplication. In addition SMMR_OK and SMRR_FAIL, this unregister function may return SMRR_APPLICATION_NOT_REGISTERED to indicate that you were not registered to listen this message.
The message routing table is stored to .INI file. You may freely modify it yourself, but it is not recommended. More than one application may want to listen same messages, so writing .INI file direct may cause problems to other applications. The category is SMSRouteTable and port numbers represent keys underneath.
Code Display 13-4 INI file: SMSRouteTable example
Here TEST application wants to receive messages 00F0 and ABBA and TES2 wants to receive message ABBA.
[SMSRouteTable]
00F0 = "TEST",11
ABBA = { "TEST",11
"TES2",11 }
There are new ComplexMonikerType values and a new ComplexMonikerBitmap:
GenItemGroups may now be of type GIGBT_NON_EXCLUSIVE, allowing the user to select more than one item at a time.
GenItemGroupClass
now has two new messages which allow you to get and set which item has the "focus"--which single item the user currently has highlighted, as opposed to the selected items:
If you are using a ContactList (from the Contact DB library), youmay set it up for multiple selections by giving it a ATTR_CONTACT_LIST_NON_EXCLUSIVE_LIST variable data field. To find out which records are selected in such a list, use
MSG_CONTACT_LIST_GET_IDS_OF_SELECTED_RECORDS.
To allow the user to narrow the choices shown in a list when they type into a text entry, use two new classes in the Foam library: FilterListClass and FilterTextClass. Their API may be found in the include file foam.goh.
These classes are only available after Build 4. Check the "
F
" field of the version number, as described above.
The Contact DB Library has four new ContactFieldType values: CFT_TEL_FAX, CFT_TEL_DATA, CFT_URL and CFT_PASSWORD.
These values are only available after Build 4. Check the "
F
" field of the version number, as described above.
Normally, a ContactList will lose track of the user's current search if the focus moves to another object. To force the list to remember the current search, send it a MSG_CONTACT_LIST_PRESERVE_SEARCH_ON_NEXT_LOST_FOCUS before it loses the focus.
This message is only available after Build 4. Check the "
F
" field of the version number, as described above.
If the user enters a valid phone number in the search box of aContactList, but that number is not found, an application mayrequest that the ContactList send out a notification using a new variable data field.
Give the ContactList a ATTR_CONTACT_LIST_NOTIFY_NUMBER_ENTERED_MSG variable data field. This field's data is a message.
The message should have parameters:
void MSG_MY_CL_NOTIFY( MemHandle phNumber = cx);
The passed block contains the phone number string. The message's recipient is responsible for freeing the passed block.
When using the Contact Log library to log a contact, if you don't know the phone number, you can pass LEF_WILDCARD_NUMBER to
LogAddEntry()
to specify that this call's number should match any phone number.