API Guide Home
(Online version only)

Header Files » Incs » 68k » libraries » telephony

HsPhoneSMS.h File Reference

Detailed Description

Header File for Phone Library API ---- SMS CATEGORY.

Notes: All implementations of the Handspring Phone Library support a common API. This API is broken up into various categories for easier management. This file defines the SMS category. These API calls are used to send/receive Short Message Service (SMS) messages.

Definition in file HsPhoneSMS.h.

Include dependency graph for HsPhoneSMS.h:

Go to the source code of this file.

Functions

Function Documentation

Err PhnLibAddAddress ( UInt16  refNum,
PhnAddressList  list,
const PhnAddressHandle  address 
)

This function adds a copy of address to the end of list. The address is not disposed of.

Parameters:
refNum,: IN:
list,: IN:
address,: IN:
Return values:
Err Error code.

char* PhnLibAddressToText ( UInt16  refNum,
PhnAddressHandle  address,
SMSAddressFormat  format 
)

Parameters:
refNum,: IN:

Parameters:
address,: IN:
format,: IN:
Return values:
Char 

Err PhnLibAPGetNth ( UInt16  refNum,
PhnAddressList  list,
Int16  index,
PhnAddressHandle *  address 
)

Parameters:
refNum,: IN:

Parameters:
list,: IN:
index,: IN:
Return values:
Err Error code.

Err PhnLibCount ( UInt16  refNum,
PhnAddressList  list,
UInt16 *  count 
)

This function returns the length of the given list. If list is 0, this function returns phnErrParam.

Parameters:
refNum,: IN:
list,: IN:
count,: IN:
Return values:
Err Error code.

Err PhnLibDeleteMessage ( UInt16  refNum,
PhnDatabaseID  msgID,
Boolean  archive 
)

This function deletes the message with the given msgID from the message database.

Parameters:
refNum,: IN:
msgID,: IN:
archive,: IN:
Return values:
This function returns 0 if there was no error during the deletion of the record. If there is no message with the given id, this function returns phnErrUnknownID.

Err PhnLibDisposeAddressList ( UInt16  refNum,
PhnAddressList  list 
)

This function disposes of the memory used by the given address list. It should be called after your done with PhnLibNewAddressList().

Parameters:
refNum,: IN:
list,: IN:
Return values:
Err Error code.

Boolean PhnLibEqual ( UInt16  refNum,
PhnAddressHandle  a,
PhnAddressHandle  b 
)

Parameters:
refNum,: IN:

Parameters:
a,: IN:
b,: IN:
Return values:
Boolean 

Err PhnLibGetAddresses ( UInt16  refNum,
PhnDatabaseID  msgID,
PhnAddressList *  list 
)

This function returns the list of addresses for the given message.

Parameters:
refNum,: IN:
msgID,: IN:
list,: IN:
Return values:
Err Error code.

Err PhnLibGetDate ( UInt16  refNum,
PhnDatabaseID  msgID,
UInt32 *  date 
)

This function returns the date of the given message in Palm OS format.

Parameters:
refNum,: IN:
msgID,: IN:
date,: IN:
Return values:
Err Error code.

DmOpenRef PhnLibGetDBRef ( UInt16  refNum  ) 

Parameters:
refNum,: IN:

Return values:
DmOpenRef 

CharPtr PhnLibGetField ( UInt16  refNum,
PhnAddressHandle  address,
PhnAddressField  field 
)

This function returns the field’s value for a given address in a newly allocated block. This function returns 0 if there was an error while retrieving the data.

Parameters:
refNum,: IN:
address,: IN:
fied,: IN:
Return values:
CharPtr 

Err PhnLibGetFlags ( UInt16  refNum,
PhnDatabaseID  msgID,
UInt32 *  flags 
)

This function returns the message’s flags.

Parameters:
refNum,: IN: Library reference number returned by HsGetPhoneLibrary().
msgID,: IN:
flags,: IN:
Return values:
Err Error code.

PhnDatabaseID PhnLibGetID ( UInt16  refNum,
PhnAddressHandle  address 
)

Parameters:
refNum,: IN:

Parameters:
address,: IN:
Return values:
PhnDatabaseID 

Err PhnLibGetLengthDetails ( UInt16  refNum,
const char *  text,
const char *  address,
PhnLibLengthInfoType *  info 
)

Parameters:
refNum,: IN:

Parameters:
text,: IN:
address,: IN:
info,: IN:
Return values:
Err Error code.

Err PhnLibGetNth ( UInt16  refNum,
const PhnAddressList  list,
Int16  index,
PhnAddressHandle *  address 
)

This function retrieves an item with the given index from list and returns it as a new block on the heap specified by address.

Parameters:
refNum,: IN:
list,: IN:
index,: IN:
address,: IN:
Return values:
Err Error code.

Err PhnLibGetOptions ( UInt16  refNum,
PhnDatabaseID  msgID,
SMSSendOptions *  options 
)

This function returns the sending options for the given message.

Parameters:
refNum,: IN:
msgID,: IN:
options,: IN:
Return values:
Err Error code.

Err PhnLibGetOwner ( UInt16  refNum,
PhnDatabaseID  msgID,
UInt32 *  owner 
)

This function returns the message’s owner.

Parameters:
refNum,: IN: Library reference number returned by HsGetPhoneLibrary().
msgID,: IN:
owner,: IN:
Return values:
Error code.

Err PhnLibGetServiceCentreAddress ( UInt16  refNum,
PhnAddressHandle *  address 
)

This function returns the number of the service center currently used for sending messages in a newly allocated address.

Parameters:
refNum,: IN:
address,: IN:
Return values:
Error code.

Err PhnLibGetSMSGateway ( UInt16  refNum,
char **  smsGateway 
)

Parameters:
refNum,: IN:

Parameters:
smsGateway,: IN:
Return values:
Err Error code.

Err PhnLibGetSMSPreference ( UInt16  refNum,
PhnSMSPrefPtr  prefP 
)

Parameters:
refNum,: IN:

Parameters:
prefP,: IN:
Return values:
Err Error code.

Err PhnLibGetSMSRingInfo ( UInt16  refNum,
PhnRingingInfoPtr  info 
)

Parameters:
refNum,: IN:

Parameters:
info,: IN:
Return values:
Err Error code.

Err PhnLibGetStatus ( UInt16  refNum,
PhnDatabaseID  msgID,
SMSMessageStatus *  status 
)

This function returns the status field of the message.

Parameters:
refNum,: IN:
msgID,: IN:
status,: IN:
Return values:
Err Error code.

const char* PhnLibGetSubstitution ( UInt16  refNum,
char  c 
)

This function returns the substitution string for a given GSM character.

Parameters:
refNum,: IN:
c,: IN:
Return values:
const 

Err PhnLibGetText ( UInt16  refNum,
PhnDatabaseID  msgID,
MemHandle *  data 
)

This function copies the text of the message into a new block of memory that must be disposed of by the caller.

Parameters:
refNum,: IN:
msgID,: IN:
data,: IN:
Return values:
Err Error code.

Err PhnLibGetType ( UInt16  refNum,
PhnDatabaseID  msgID,
SMSMessageType *  type 
)

This function returns the message’s type. A client application typically uses the type to map messages to categories.

Parameters:
refNum,: IN:
msgID,: IN:
type,: IN:
Return values:
Err Error code.

Boolean PhnLibHasName ( UInt16  refNum,
PhnAddressHandle  address 
)

Parameters:
refNum,: IN:

Parameters:
address,: IN:
Return values:
Boolean 

Boolean PhnLibIsLegalCharacter ( UInt16  refNum,
char  c 
)

This function returns true if the given Palm OS character is a legal GSM character. If this function returns false, the given character does not exist within the GSM alphabet.

Parameters:
refNum,: IN:
c,: IN:
Return values:
Boolean 

Int16 PhnLibLength ( UInt16  refNum,
const char *  text,
Boolean  inMessages,
Boolean  substitution 
)

This function returns the length of the given text in characters or messages.

Parameters:
refNum,: IN:
text,: IN:
inMessages,: IN:
substitution,: IN:
Return values:
Int16 

char PhnLibMapCharacter ( UInt16  refNum,
char  c 
)

This function maps the given Palm OS character to its equivalent in the GSM alphabet.

Parameters:
refNum,: IN:
c,: IN:
Return values:
char 

PhnAddressHandle PhnLibNewAddress ( UInt16  refNum,
const CharPtr  number,
PhnDatabaseID  id 
)

Parameters:
refNum,: IN:

Parameters:
number,: IN:
id,: IN:
Return values:
PhnAddressHandle 

PhnAddressList PhnLibNewAddressList ( UInt16  refNum  ) 

This function returns a new address list. The list is initially empty and must be disposed of by the caller using PhnLibDisposeAddressList() or MemHandleFree().

Parameters:
refNum,: IN:
Return values:
PhnAddressList 

PhnDatabaseID PhnLibNewMessage ( UInt16  refNum,
SMSMessageType  type 
)

Create a new message of the given message type and return the ID of the new record in the message database. All fields are either empty (e.g. message’s text) or contain default values (e.g. sending options).

Parameters:
refNum,: IN:
type,: IN: Incoming or Outcoming message. See SMSMessageType for more details.
Return values:
Returns either the ID of the new message record or phnErrUnknownID if there was not sufficient memory to allocate a new message.

Err PhnLibQuerySMSMT ( UInt16  refNum  ) 

Parameters:
refNum,: IN:

Return values:
Err Error code.

Err PhnLibReleaseDBRef ( UInt16  refNum,
DmOpenRef  db 
)

Parameters:
refNum,: IN:

Parameters:
db,: IN:
Return values:
Err Error code.

Err PhnLibSendMessage ( UInt16  refNum,
PhnDatabaseID  msgID,
Boolean  progress 
)

This function sends the message to all the recipients.

Parameters:
refNum,: IN:
msgID,: IN:
progress,: IN:
Return values:
phnErrUnknownID,: If there is no message with the given ID. phnErrIllegalStatus: If the message’s status is not kNone or kPending phnErrNotAllowed: If the error flag is set. It is not permitted to send messages when the error flag is set.

Err PhnLibSendPendingMessages ( UInt16  refNum  ) 

Parameters:
refNum,: IN:

Return values:
Err Error code.

Err PhnLibSendSMSMTAck ( UInt16  refNum,
UInt8  transactionId,
Boolean  ack 
)

Parameters:
refNum,: IN:

Parameters:
transactionID,: IN:
acK,: IN:
Return values:
Err Error code.

Err PhnLibSetAddresses ( UInt16  refNum,
PhnDatabaseID  msgID,
const PhnAddressList  list 
)

This function updates the list of addresses with the given list of addresses.

Parameters:
refNum,: IN:
msgID,: IN:
list,: IN:
Return values:
Err Error code.

Err PhnLibSetDate ( UInt16  refNum,
PhnDatabaseID  msgID,
UInt32  date 
)

This function sets the date of the given message. The date must be given in Palm OS format (as returned by TimGetSeconds).

Parameters:
refNum,: IN:
msgID,: IN:
date,: IN:
Return values:
Err Error code.

Err PhnLibSetField ( UInt16  refNum,
PhnAddressHandle  address,
PhnAddressField  field,
const char *  data 
)

This function lets the specified field of address to the given data. This function returns 0 if the field was modified without an error.

Parameters:
refNum,: IN:
address,: IN:
field,: IN:
data,: IN:
Return values:
Err Error Code.

Err PhnLibSetFlags ( UInt16  refNum,
PhnDatabaseID  msgID,
UInt32  flags 
)

This function updates a message’s flags.

Parameters:
refNum,: IN:
msgID,: IN:
flags,: IN:
Return values:
Err Error code.

Err PhnLibSetID ( UInt16  refNum,
PhnAddressHandle  address,
PhnDatabaseID  id 
)

Parameters:
refNum,: IN:

Parameters:
address,: IN:
id,: IN:
Return values:
Err Error code.

Err PhnLibSetNth ( UInt16  refNum,
PhnAddressList  list,
Int16  index,
const PhnAddressHandle  address 
)

This function replaces the data of the item with the given index from list by the given address.

Parameters:
refNum,: IN:
list,: IN:
index,: IN:
address,: IN:
Return values:
Err Error code.

Err PhnLibSetNumber ( UInt16  refNum,
PhnAddressHandle  address,
const char *  number 
)

Parameters:
refNum,: IN:

Parameters:
address,: IN:
number,: IN:
Return values:
Err Error Code.

Err PhnLibSetOptions ( UInt16  refNum,
PhnDatabaseID  msgID,
const SMSSendOptions *  options 
)

This function updates the sending options for the given message.

Parameters:
refNum,: IN:
msgID,: IN:
options,: IN:
Return values:
Err Error code.

Err PhnLibSetOwner ( UInt16  refNum,
PhnDatabaseID  msgID,
UInt32  owner 
)

This function updates the given message’s owner.

Parameters:
refNum,: IN:
msgID,: IN:
owner,: IN
Return values:
Err Error code.

Err PhnLibSetServiceCentreAddress ( UInt16  refNum,
const PhnAddressHandle  address 
)

This function sets the number of the service center to be used for sending the SMS messages.

Parameters:
refNum,: IN:
address,: IN:
Return values:
Err Error code.

Err PhnLibSetSMSCallbackNumber ( UInt16  refNum,
const CharPtr  number,
PhnDatabaseID  msgID 
)

Parameters:
refNum,: IN:

Parameters:
number,: IN:
msgID,: IN:
Return values:
Err Error code.

Err PhnLibSetSMSPreference ( UInt16  refNum,
PhnSMSPrefPtr  prefP 
)

Parameters:
refNum,: IN:

Parameters:
prefP,: IN:
Return values:
Err Error code.

Err PhnLibSetSMSRingInfo ( UInt16  refNum,
PhnRingingInfoPtr  info 
)

Parameters:
refNum,: IN:

Parameters:
info,: IN:
Return values:
Err Error code.

Err PhnLibSetStatus ( UInt16  refNum,
PhnDatabaseID  msgID,
SMSMessageStatus  status 
)

This function sets the status of the given message.

Parameters:
refNum,: IN:
msgID,: IN:
status,: IN:
Return values:
Err Error code.

Err PhnLibSetText ( UInt16  refNum,
PhnDatabaseID  msgID,
const char *  data,
Int16  size 
)

This function sets the text of the message to the given text.

Parameters:
refNum,: IN:
msgID,: IN:
data,: IN:
size,: IN:
Return values:
0,: if the text was updated successfully. phnErrIllegalChars: If the text contains illegal characters

Top Palm Developer Network
© 2004-2008, Palm, Inc. All rights reserved.
Generated on Fri Jun 13 10:07:26 2008 for Palm API Guide