|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
-> |
messageType |
The message type. This is one of the SMS Message Type Constants. |
-> |
index |
The index of the SMS message in the phone's storage that is to be deleted. Note that the message is deleted from the storage area selected by a call to the TelSmsSelectStorage function. Note that the index is zero-based. |
The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedCDMAType structure for CDMA messages.
typedef struct _TelSmsDeliveryAdvancedCDMAType { UInt8 messageType; TelSmsDateTimeType validityPeriod; UInt8 priority; UInt8 privacy; Boolean alertOnDeliveryRequest; Boolean manualAckRequest; UInt8 voiceMessageNumber; UInt8 callbackNumberSize; Char *callbackNumberAddress; UInt8 languageIndicator; } TelSmsDeliveryAdvancedCDMAType;
|
messageType |
The type of the message. This must be one of the SMS Message Type Constants. |
|
validityPeriod |
An TelSmsDateTimeType structure that specifies the amount of time for which the message is valid. |
|
priority |
The message priority. This must be one of the SMS Message Urgency Constants. |
|
privacy |
The privacy type of the message. This must be one of the SMS Message Privacy Constants. |
|
alertOnDeliveryRequest |
true if the user is to be alerted upon delivery of this message, and false if not. |
|
manualAckRequest |
true if a reply is requested from the user, and false if not. |
|
voiceMessageNumber |
|
|
callbackNumberSize |
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumberAddress string. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
|
callbackNumberAddress |
A buffer into which the callback number address string is stored. Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
|
languageIndicator |
|
The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedGSMType structure for GSM messages.
typedef struct _TelSmsDeliveryAdvancedGSMType { UInt16 protocolId; Boolean replyPath; Char *serviceCenterNumber; UInt8 serviceCenterNumberSize; } TelSmsDeliveryAdvancedGSMType
<- |
protocolId |
The protocol used for this message. This is one of the SMS Message Transport Protocol Constants. |
<- |
replyPath |
If this value is set, then you use the serviceCenterNumber to reply to this message. If this value is not set, you use the default service center provided by your network operator. |
<-> |
serviceCenterNumber |
A buffer into which the service center number string is stored. Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
<-> |
seviceCenterNumberSize |
When the structure is used as an input parameter, this is the allocated size, in bytes, of the serviceCenterNumber string. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
The TelSmsDeliveryMessageType structure includes a TelSmsDeliveryAdvancedTDMAType structure for TDMA messages.
typedef struct _TelSmsDeliveryAdvancedTDMAType { UInt8 messageType; TelSmsDateTimeType validityPeriod; UInt8 priority; UInt8 privacy; Boolean alertOnDeliveryRequest; Boolean manualAckRequest; UInt8 voiceMessageNumber; UInt8 callbackNumberSize; Char *callbackNumberAddress; UInt8 languageIndicator; } TelSmsDeliveryAdvancedTDMAType;
|
messageType |
The type of the message. This must be one of the SMS Message Type Constants. |
|
validityPeriod |
An TelSmsDateTimeType structure that specifies the amount of time for which the message is valid. |
|
priority |
The message priority. This must be one of the SMS Message Urgency Constants. |
|
privacy |
The privacy type of the message. This must be one of the SMS Message Privacy Constants. |
|
alertOnDeliveryRequest |
true if the user is to be alerted upon delivery of this message, and false if not. |
|
manualAckRequest |
true if a reply is requested from the user, and false if not. |
|
voiceMessageNumber |
|
|
callbackNumberSize |
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumberAddress string. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
|
callbackNumberAddress |
A buffer into which the callback telephone number address string is stored. Note that if this buffer is too small to contain the entire retrieved string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
|
languageIndicator |
|
The TelSmsReadMessage function uses a TelSmsDeliveryMessageType structure to retrieve information about a delivered message.
typedef struct _TelSmsDeliveryMessageType { UInt16 version; UInt16 index; UInt32 messageIdentifier; TelSmsDateTimeType timeStamp; UInt16 dataSize; UInt8 *data; UInt8 dataCodingScheme; UInt8 originatingAddressSize; Char *originatingAddress; Boolean otherToReceive; Boolean reportDeliveryIndicator; UInt8 standardType; union { TelSmsDeliveryAdvancedGSMType advancedGSM; TelSmsDeliveryAdvancedCDMAType advancedCDMA; TelSmsDeliveryAdvancedTDMAType advancedTDMA; } advancedParams; UInt8 extensionsCount; TelSmsExtensionType *extensionsP; } TelSmsDeliveryMessageType;
-> |
version |
The version of the SMS API associated with this message. |
<-> |
index |
Upon return, the SMS index of the message on the phone. This is a 0-based index. This value is used for input only when calling the TelSmsReadMessage function to read one SMS at a time. |
<- |
messageIdentifier |
The message identifier. |
<- |
timeStamp |
The message time stamp. This is a TelSmsDateTimeType structure. |
<-> |
dataSize |
The size of the data buffer. When the structure is used as an input parameter, this is the allocated size of the data buffer. Upon return, this is the actual size of the message data. If the buffer is too small to contain the entire message, this field is assigned the entire length of the message, and the function using this structure generates a telErrBufferSize error. |
<-> |
data |
A buffer into which the retrieved data is stored. Note that if this buffer is too small to contain the entire retrieved message, the end of the message is truncated and the function using this structure generates a telErrBufferSize error. |
<- |
dataCodingScheme |
The coding scheme used for the data. This is one of the SMS Data Coding Scheme Constants. |
<-> |
originatingAddressSize |
The size of the originatingAddress buffer. When the structure is used as an input parameter, this is the allocated size of the originatingAddress buffer. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
<-> |
originatingAddress |
A buffer into which the originating address string is stored. Note that if this buffer is too small to contain the entire string, the end of the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
<- |
otherToReceive |
Indicates whether there are more messages waiting to be received from the service center to the mobile device. |
<- |
reportDeliveryIndicator |
If true, indicates that the originating user has asked the network to send a delivery report. |
<- |
standardType |
Indicates which field of the advancedParams union contains the message information. This is one of the Network Type Constants described in Chapter 71, "Telephony Network." If this value is kTelNwkCDMA, then the advancedParams union contains a TelSmsDeliveryAdvancedCDMAType structure, and similarly for the other values. |
|
advancedParams |
Advanced message information for GSM, CDMA, or TDMA messages. This is one of the following structure types: TelSmsDeliveryAdvancedGSMType TelSmsDeliveryAdvancedCDMAType TelSmsDeliveryAdvancedTDMAType |
<-> |
extensionsCount |
On input, this is the number of extension structures allocated for this message. You must allocate at least one structure to specify the multipart information. Upon return, this is the number of extensions in the SMS header. If the SMS header contains more extensions than you have allocated, the available extension structures are filled, and this function generates a telErrBufferSize error. |
<-> |
extensionsP |
A pointer to an array of TelSmsExtensionType structures that you have allocated for this message. You must allocate this array before using this structure. |
The TelSmsExtensionType structure specifies multipart information about a message.
typedef struct _TelSmsExtensionType UInt8 extensionTypeId; union { TelSmsMultiPartExtensionType mp; TelSmsNbsExtensionType nbs; TelSmsUserExtensionType user; } extension; } TelSmsExtensionType;
<-> |
extensionTypeId |
Identifies the type of SMS extension structure found in the extension union. This is one of the SMS Extension Type Constants. If the value of this field is kTelSmsMultipartExtensionTypeId, then the extension union contains a TelSmsMultiPartExtensionType structure. If the value of this field is kTelSmsNbsExtensionTypeId or kTelSmsNbs2ExtensionTypeId, then the union contains a TelSmsNbsExtensionType structure. The difference between these two is that kTelSmsNbs2ExtensionTypeId indicates that the port value is a long instead of a short. If this field contains any other value, then the union contains a TelSmsUserExtensionType structure. |
<- |
extension |
The extension information, which is one of the following structure types: TelSmsMultiPartExtensionType TelSmsNbsExtensionType TelSmsUserExtensionType |
The TelSmsGetAvailableStorage function uses a TelSmsGetAvailableStorageType structure to retrieve information about the storage available on the phone.
typedef struct _TelSmsGetAvailableStorageType UInt16 count; UInt8 *storagesP; } TelSmsGetAvailableStorageType;
<-> |
count |
The size of the storagesP buffer. When the structure is used as an input parameter, this is the allocated number of values in the buffer. Upon return, this is the total number of storage areas in the phone. |
<- |
storagesP |
A buffer into which the retrieved storage IDs are stored. Each value stored into the buffer is one of the SMS Storage ID Constants. |
The TelSmsGetMessageCount function uses a TelSmsGetMessageCountType structure to retrieve information about messages in the currently selected storage.
typedef struct _TelSmsGetMessageCountType { UInt8 messageType; UInt16 slots; UInt16 count; } TelSmsGetMessageCountType;
-> |
messageType |
The type of message for which you want to retrieve the count. This must be one of the SMS Message Type Constants. You must fill this in on input to the TelSmsGetMessageCount function. |
<- |
slots |
The total number of message slots available in the currently selected storage area (for all message types). |
<- |
count |
The number of filled slots for the specified messageType in the currently selected storage area. |
The TelSmsSendManualAcknowledge function uses a TelSmsManualAckType structure to specify the information used to send a message acknowledgment.
typedef struct _TelSmsManualAckType { UInt16 version; Char *destinationAddress; UInt32 messageId; UInt16 dataSize; UInt8 *data; UInt8 dataCodingScheme; UInt8 responseCode; } TelSmsManualAckType;
|
version |
The version of the SMS API used for this acknowledgment. |
|
destinationAddress |
The destination address. For GSM, the length of this address is 12 bytes. For CDMA, the length is up to 128 bytes. |
|
messageId |
Upon return, the ID of the acknowledgment. |
|
dataSize |
The size of the data buffer. When the structure is used as an input parameter, this is the allocated size of the data buffer. Upon return, this is the actual size of the data. If the buffer is too small to contain all of the data, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error. |
|
data |
A buffer into which the retrieved data is stored. Note that if this buffer is too small to contain the all of the retrieved data, the data is truncated and the function using this structure generates a telErrBufferSize error. |
|
dataCodingScheme |
The coding scheme used for the data. This must be one of the SMS Data Coding Scheme Constants. |
|
responseCode |
The response code. The value of this field depends on the network being used. |
The TelSmsExtensionType structure uses a TelSmsMultiPartExtensionType structure to describe information about a multipart message.
typedef struct _TelSmsMultiPartExtensionType UInt16 bytesSent; UInt16 partCurrent; UInt16 partCount; UInt16 partId; } TelSmsMultiPartExtensionType;
The TelSmsExtensionType structure uses a TelSmsNbsExtensionType structure to describe information about a NBS message.
typedef struct _TelSmsNbsExtensionType UInt16 destPort; UInt16 srcPort; } TelSmsNbsExtensionType;
The TelSmsReadMessages function uses a TelSmsReadMessagesType structure to retrieve messages from the currently selected storage area.
typedef struct _TelSmsReadMessagesType UInt16 first; UInt16 count; TelSmsDeliveryMessageType *messagesP; } TelSmsReadMessagesType;
-> |
first |
The index of the first message to retrieve. Message indexes are zero-based. |
<-> |
count |
The size of the messagesP buffer. When the structure is used as an input parameter, this is the allocated number of pointers in the messagesP buffer. Upon return, this is the number of messages that could be retrieved. If the messagesP buffer is too small to contain all of the messages, this field is assigned the entire count, and the function using this structure generates a telErrBufferSize error. |
<-> |
messagesP |
An array of pointers to TelSmsDeliveryMessageType structures, each of which is filled in with a retrieved message, if available. |
The TelSmsReadReports function uses a TelSmsReadReportsType structure to retrieve reports from the currently selected storage area.
typedef struct _TelSmsReadReportsType UInt16 first; UInt16 count; TelSmsReportType *reportsP; } TelSmsReadReportsType;
-> |
first |
The index of the first report to retrieve. Report indexes are zero-based. |
<-> |
count |
The size of the reportsP buffer. When the structure is used as an input parameter, this is the allocated number of pointers in the reportsP buffer. Upon return, this is the actual number of reports that could be read. If the buffer is too small to contain all of the reports, this field is assigned the entire count, and the function using this structure generates a telErrBufferSize error. |
<-> |
reportsP |
An array of pointers to TelSmsReportType structures, each of which is filled in with a retrieved message, if available. Note that if this buffer is too small to contain all of the retrieved reports, the function using this structure generates a telErrBufferSize error. |
The TelSmsReadSubmittedMessages function uses a TelSmsReadSubmittedMessagesType structure to retrieve submitted messages from the currently selected storage area.
typedef struct _TelSmsReadMessagesType UInt16 first; UInt16 count; TelSmsDeliveryMessageType *submittedsP; } TelSmsReadSubmittedMessagesType;
-> |
first |
The index of the first message to retrieve. Message indexes are zero-based. |
<-> |
count |
The size of the submittedsP buffer. When the structure is used as an input parameter, this is the allocated number of pointers in the submittedsP buffer. Upon return, this is the number of messages that were actually read. |
<-> |
submittedsP |
An array of pointers to TelSmsSubmittedMessageType structures, each of which is filled in with a retrieved message, if available. |
The TelSmsReadReport function uses a TelSmsReportType structure to retrieve a report from the report storage area.
typedef struct _TelSmsReportType { UInt16 version; UInt16 index; UInt8 reportType; UInt32 messageId; UInt16 dataSize; UInt8 *data; UInt8 dataCodingScheme; Char *originatingAddress; UInt8 originatingAddressSize; UInt8 report; TelSmsDateTimeType timeStamp; } TelSmsReportType;
-> |
version |
|
<- |
index |
The index of the report in the phone storage area. |
<- |
reportType |
The delivery report type. |
<- |
messageId |
The message ID. |
<-> |
dataSize |
The size of the data buffer. When the structure is used as an input parameter, this is the allocated size of the data buffer. Upon return, this is the actual size of the data. If the buffer is too small to contain all of the data, this field is assigned the entire length of the data, and the function using this structure generates a telErrBufferSize error. |
<-> |
data |
A buffer into which the retrieved data is stored. Note that if this buffer is too small to contain the all of the retrieved data, the data is truncated and the function using this structure generates a telErrBufferSize error. |
<- |
dataCodingScheme |
The encoding scheme used for the report data. This must be one of the SMS Data Coding Scheme Constants. |
<-> |
originatingAddress |
A buffer into which the originating address is stored. Note that if this buffer is too small to contain the entire retrieved string, the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBuffrSize error. |
<-> |
originatingAddressSize |
The size of the originatingAddress buffer. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
<- |
report |
The ID of the delivery confirmation report associated with the message. |
<- |
timeStamp |
An TelSmsDateTimeType structure that stores the time at which the message corresponding to the report was received. |
typedef struct _TelSmsSendMessageType { UInt32 messageId; TelSmsSubmitMessageType message; } TelSmsSendMessageType;
<- |
messageId |
The SMS ID that was assigned by the telephone to the outgoing message. For a multi-part message, each part has its own message ID. |
-> |
message |
A structure of type TelSmsSubmitMessageType that contains the message data and parameters. |
The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedCDMAType structure for CDMA messages.
typedef struct _TelSmsSubmitAdvancedCDMAType { Boolean manualAckRequest; UInt8 messageType; TelSmsDateTimeType deferredDate; UInt8 priority; UInt8 privacy; Boolean alertOnDeliveryRequest; Char *callbackNumber; UInt8 callbackNumberSize; } TelSmsSubmitAdvancedCDMAType;
|
manualAckRequest |
true if a reply is requested from the user, and false if not. |
|
messageType |
The type of the message. This must be one of the SMS Message Type Constants. |
|
deferredDate |
|
|
priority |
|
|
privacy |
The privacy type of the message. This must be one of the SMS Message Privacy Constants. |
|
alertOnDeliveryRequest |
true if the user is to be alerted upon delivery of this message, and false if not. |
|
callbackNumber |
A buffer into which the retrieved callback telephone number string is stored. Note that if this buffer is too small to contain the entire retrieved string, the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
|
callbackNumberSize |
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumber string. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedGSMType structure for GSM messages.
typedef struct _TelSmsSubmitAdvancedGSMType { UInt16 protocolId; Boolean rejectDuplicatedRequest; Boolean replyPath; Char *serviceCenterNumber; UInt8 serviceCenterNumberSize; } TelSmsSubmitAdvancedGSMType;
The TelSmsSubmitMessageType structure includes a TelSmsSubmitAdvancedTDMAType structure for TDMA messages.
typedef struct _TelSmsSubmitAdvancedTDMAType { Boolean manualAckRequest; UInt8 messageType; TelSmsDateTimeType deferredDate; UInt8 priority; UInt8 privacy; Boolean alertOnDeliveryRequest; Char *callbackNumber; UInt8 callbackNumberSize; } TelSmsSubmitAdvancedTDMAType;
|
manualAckRequest |
true if a reply is requested from the user, and false if not. |
|
messageType |
The type of the message. This must be one of the SMS Message Type Constants. |
|
deferredDate |
|
|
priority |
|
|
privacy |
The privacy type of the message. This must be one of the SMS Message Privacy Constants. |
|
alertOnDeliveryRequest |
true if the user is to be alerted upon delivery of this message, and false if not. |
|
callbackNumber |
A buffer into which the retrieved callback telephone number string is stored. Note that if this buffer is too small to contain the entire retrieved string, the string is truncated (and ends with the null terminator character) and the function using this structure generates a telErrBufferSize error. |
|
callbackNumberSize |
When the structure is used as an input parameter, this is the allocated size, in bytes, of the callbackNumber string. Upon return, this is the actual size of the string, including the null terminator character. If the buffer is too small to contain the entire retrieved string, this field is assigned the entire length of the string, and the function using this structure generates a telErrBufferSize error. |
The TelSmsReadReports and TelSmsSendMessageType structures use a TelSmsSubmitMessageType structure to stored reports retrieved from the currently selected storage area.
typedef struct _TelSmsSubmitMessageType { UInt16 version; Boolean networkDeliveryRequest; Char *destinationAddress; UInt8 destinationAddressSize; UInt16 dataSize; UInt8 *data; UInt8 dataCodingScheme; TelSmsDateTimeType validityPeriod; UInt8 standardType; union { TelSmsSubmitAdvancedGSMType advancedGSM; TelSmsSubmitAdvancedCDMAType advancedCDMA; TelSmsSubmitAdvancedTDMAType advancedTDMA; } advancedParams; UInt8 extensionsCount; TelSmsExtensionType *extensionsP; } TelSmsSubmitMessageType;
-> |
version |
The version of the SMS API associated with this message. |
-> |
networkDeliveryRequest |
If this value is true, the service center accepts the submit message. |
<-> |
destinationAddress |
A buffer that contains the phone number of the message recipient. |
<-> |
destinationAddressSize |
The size of the destination address string. |
<-> |
dataSize |
The size of the data buffer. |
<-> |
data |
A buffer into which the retrieved message data is stored. |
-> |
dataCodingScheme |
The coding scheme used for the data. This is one of the SMS Data Coding Scheme Constants. |
-> |
validityPeriod |
An TelSmsDateTimeType structure that specifies the amount of time for which the message is valid. |
-> |
standardType |
Indicates which field of the advancedParams union contains the message information. This must be one of the Network Type Constants described in Chapter 71, "Telephony Network." If this value is kTelNwkCDMA, then the advancedParams union contains a TelSmsDeliveryAdvancedCDMAType structure, and similarly for the other values. |
-> |
advancedParams |
Advanced message information for GSM, CDMA, or TDMA messages. This is a pointer to one of the following structure types: TelSmsSubmitAdvancedCDMAType TelSmsDeliveryAdvancedGSMType TelSmsDeliveryAdvancedTDMAType |
<-> |
extensionsCount |
The number of extension structures allocated for this message. You must allocate at least one structure to specify the multipart information. |
<-> |
extensionsP |
A pointer to an array of TelSmsExtensionType structures that you have allocated for this message. |
The TelSmsReadSubmittedMessage function uses a TelSmsSubmittedMessageType structure to retrieve reports from the currently selected storage area.
typedef struct _TelSmsSubmittedMessageType { UInt16 index; TelSmsSubmitMessageType message; } TelSmsSubmittedMessageType;
-> |
index |
The index of the message on the phone. |
<- |
message |
A TelSmsSubmitMessageType structure that represents the message. |
The TelSmsExtensionType structure uses a TelSmsUserExtensionType structure to describe a user-defined extended message header.
typedef struct _TelSmsUserExtensionType UInt8 *extHeader; UInt8 extHeaderSize; } TelSmsUserExtensionType;
This section describes the constants used with the SMS service set of the telephony API.
The SMS extension type constants describe the type of extension used to represent part of a message.
The SMS message type constants describe the delivery type of a message.
The SMS message transport protocol constants describe the protocol used to deliver a message.
The SMS storage ID constants describe the storage location of a message.
The SMS data coding scheme constants describe the encoding used for SMS data.
The SMS message urgency constants describe the priority level of a message in a TelSmsDeliveryAdvancedCDMAType or TelSmsDeliveryAdvancedTDMAType structure.
Constant |
Value |
Description |
---|---|---|
kTelSmsUrgencyNormal |
0 |
Normal urgency. |
kTelSmsUrgencyUrgent |
1 |
An urgent message. |
kTelSmsUrgencyEmergency |
2 |
An emergency message. |
The SMS message privacy constants describe the privacy type of a message in a CDMA or TDMA advanced parameters.
This section describes the functions used with the SMS service set of the telephony API.
Delete an SMS report, delivered message, or submitted message.
Err TelSmsDeleteMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsDeleteMessageType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelSmsDeleteMessageType structure that specifies the index and type of the message to delete. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
If the deleted message has been delivered, the deletion is performed in the current storage, which you can set with the TelSmsSelectStorage function.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Retrieve the list of all available storage on the phone.
Err TelSmsGetAvailableStorage(UInt16 iRefnum, TelAppID iAppId, TelSmsGetAvailableStorageType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelSmsGetAvailableStorageType structure that is filled in with information about the storage areas available on the phone. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsGetAvailableStorageType structure passed to this function in the ioParamP parameter. |
functionId |
kTelSmsGetAvailableStorageMessage |
The count of storage areas available on the phone is stored into the count field of the TelSmsGetAvailableStorageType structure referenced by ioParamP, and the storage ID of each available room is stored into the buffer referenced by the storagesP field. If the storagesP buffer is too small to contain all of the storage IDs, the buffer is truncated and this function returns the telErrBufferSize error. The count field of the structure is always updated to contain the total number of available storage areas on the phone.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Returns the maximum length, in bytes, of a message on the current network.
Err TelSmsGetDataMaxSize(UInt16 iRefnum, TelAppID iAppId, UInt16 *oSizeP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oSizeP | A pointer to an unsigned integer value that is updated witht he maximum length of an SMS message on the current network. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
You can use this function to determine the maximum size you need to allocate to read a message.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsReadMessage, TelSmsReadMessages
Retrieve the total number of message slots, and the number of filled slots for the specified message type.
Err TelSmsGetMessageCount(UInt16 iRefnum, TelAppID iAppId, TelSmsGetMessageCountType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelSmsGetMessageCountType structure that specifies the message type and is filled in with the count information. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsGetMessageCountType structure passed to this function in the ioParamP parameter. |
functionId |
kTelSmsGetMessageCountMessage |
The currently selected storage area pertains only to delivered messages; other message types are stored on the phone, but not in a specific storage area. If you specify delivered messages, this function retrieves information about the messages in the currently selected SMS storage area on the phone. If you specify a different message type, this function retrieves information about the messages in the phone.
You specify the message type by assigning one of the SMS Message Type Constants to the messageType field of the TelSmsGetMessageCountType structure before calling this function.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Retrieve the ID of the currently selected storage area on the phone.
Err TelSmsGetSelectedStorage(UInt16 iRefnum, TelAppID iAppId, UInt8 *oStorageIdP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oStorageIdP | A pointer to an unsigned byte value that is assigned the ID of the currently selected storage area on the phone. The assigned ID value is one of the SMS Storage ID Constants. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
The currently selected storage area pertains only to delivered messages; other message types are stored on the phone, but not in a specific storage area.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Return a unique part identifier to assign to the partId field of a submit message.
Err TelSmsGetUniquePartId(UInt16 iRefnum, TelAppID iAppId, UInt16 *oUniqueIdP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<- oUniqueIdP | A pointer to a unsigned integer value. Upon return, this is the unique part ID value. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
This function corresponds to the kTelUrqSmsGetUniquePartIdMessage value.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Retrieve a delivered message from the currently selected storage area.
Err TelSmsReadMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsDeliveryMessageType *ioMessageP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioMessageP | A pointer to a TelSmsDeliveryMessageType structure that is filled in with the message. |
On input, the index field of this structure contains the index of the message that you want retrieved. Message indexes are zero-based. |
On input, the extensionsCount field specifies the number of extensions allocated in the extensionsP array. You must allocate at least one multi-part extension, even for a single-part message. |
On input, the dataSize field specifies the allocated size of the data buffer, and the originatingAddressSize field specifies the allocated size of the originatingAddress string. Upon return, each size field specifies the complete size of the data that was stored into the buffer, even if the data had to be truncated to fit. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsDeliveryMessageType structure passed to this function in the ioMessageP parameter. |
functionId |
kTelSmsReadMessageMessage |
The message data is stored into the data field of the TelSmsDeliveryMessageType structure referenced by ioMessageP. If the complete message data is too large to fit into the allocated size of the data field, the message data is truncated and this function returns the telErrBufferSize error. The dataSize field of the structure is always updated to contain the actual size, in bytes, of the message data.
The originating address string is stored into the originatingData field of the TelSmsDeliveryMessageType structure referenced by ioMessageP. If the complete string is too large to fit into the allocated size of the originatingData field, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The originatingAddressSize field of the structure is always updated to contain the actual size of the string.
Before calling this function, you need to allocate a number of fields and structures in and related to the TelSmsDeliveryMessage structure:
Allocate each address field with a size of at least kTelMaxPhoneNumberLen + 1.
For example, for a GSM message, you must allocate the originatingAddress and serviceCenterNumber fields in the TelSmsDeliveryAdvancedGSMType structure in the TelSmsDeliveryMessage structure.
Allocate the message field data to have the maximum size of a message on the current network. You can determine this value by calling the TelSmsGetDataMaxSize function.
Allocate at least one TelSmsExtensionType structure in the TelSmsDeliveryMessage structure. You must have at least one extension structure, even if your message has only a single part. If you do not allocate enough extensions for the message, TelSmsReadMessage returns an error. Palm recommends allocating between 3 and 5 extensions for a message.
You should not allocate a pointer for user extension data. If you receive user extension data, the user extension pointer will reference a block in the message data. Do not deallocate the user extension data when you release the structure.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Retrieve a range of delivered messages from the currently selected storage area.
Err TelSmsReadMessages(UInt16 iRefnum, TelAppID iAppId, TelSmsReadMessagesType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelSmsReadMessagesType structure. |
On input, the first field of this structure specifies the index of the first message to retrieve. Message indexes are zero-based. |
On input the count field of this structure specifies the allocated size of the messagesP buffer. Upon return, the count field specifies the actual number of messages that were available, even if that many could not fit into the buffer. |
The messagesP buffer must contain pointers to TelSmsDeliveryMessageType structures that have been allocated. Each of these structures must be initialized as described for the TelSmsReadMessage function. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsReadMessagesType structure passed to this function in the ioParamP parameter. |
functionId |
kTelSmsReadMessagesMessage |
If the message data or originating address string data for any of the retrieved messages is larger than the allocated size of its corresponding buffer, the data is truncated into the buffer, and this function returns the telErrBufferSize error.
For more information about using this function and allocating structures for its use, see the Comments description for the TelSmsReadMessage function.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Read a report from the currently selected storage area.
Err TelSmsReadReport(UInt16 iRefnum, TelAppID iAppId, TelSmsReportType *ioReportP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioReportP | A pointer to a TelSmsReportType structure. |
On input the index field of this structure contains the index of the message that you want retrieved. Message indexes are zero-based. |
On input, the dataSize field specifies the allocated size of the data buffer, and the originatingAddressSize field specifies the allocated size of the originatingAddress string. Upon return, each size field specifies the complete size of the data that was stored into the buffer, even the data had to be truncated to fit. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsReportType structure passed to this function in the ioReportP parameter. |
functionId |
kTelSmsReadReportMessage |
The report data is stored into the data field of the TelSmsReportType structure referenced by ioReportP. If the complete message data is too large to fit into the allocated size of the data field, the report data is truncated and this function returns the telErrBufferSize error. The dataSize field of the structure is always updated to contain the actual size, in bytes, of the report data.
The originating address string is stored into the originatingData field of the TelSmsReportType structure referenced by ioReportP. If the complete string is too large to fit into the allocated size of the originatingData field, the string is truncated (and ends with the null terminator character) and this function returns the telErrBufferSize error. The originatingAddressSize field of the structure is always updated to contain the actual size of the string.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsSelectStorage, TelSmsSendMessage
Retrieve a range of reports from the currently selected storage.
Err TelSmsReadReports(UInt16 iRefnum, TelAppID iAppId, TelSmsReadReportsType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelSmsReadReportsType structure. |
On input, the first field of this structure specifies the index of the first report to retrieve. Report indexes are zero-based. |
On input the count field of this structure specifies the allocated size of the reportsP buffer. Upon return, the count field specifies the actual number of reports that were available, even if that many could not fit into the buffer. |
The reportsP buffer must contain pointers to TelSmsReportType structures that have been allocated. Each of these structures must be initialized as described for the TelSmsReadReport function. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsReadReportsType structure passed to this function in the ioParamP parameter. |
functionId |
kTelSmsReadReportsMessage |
If the report data or originating address string data for any of the retrieved messages is larger than the allocated size of its corresponding buffer, the data is truncated into the buffer, and this function returns the telErrBufferSize error. For more information, see the Comments description for the TelSmsReadReport function.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsSelectStorage, TelSmsSendMessage
Read a previously submitted message that was kept on the phone after being sent.
Err TelSmsReadSubmittedMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsSubmittedMessageType *ioMessageP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioMessageP | A pointer to a TelSmsSubmitMessageType structure that is filled in with the message. |
On input, the index field contains the index of the message that you want retrieved. Message indexes are zero-based. |
Upon return, the message field structure is filled in with the message information. You must initialize the buffer size fields of this structure prior to calling this function, including the dataSize, callbackNumberSize, serviceCenterNumberSize, and destinationAddressSize fields. Each of these fields is initialized with the allocated size of its corresponding buffer. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsSubmitMessageType structure passed to this function in the ioMessageP parameter. |
functionId |
kTelSmsSubmittedMessageMessage |
The message data is stored into the data field of the TelSmsSubmitMessageType structure referenced by ioMessageP. If the complete message data is too large to fit into the allocated size of the data field, the end of the message data is truncated and this function returns the telErrBufferSize error. The dataSize field of the structure is always updated to contain the actual size, in bytes, of the message data.
The same strategy applies to the callbackNumber buffer and callbackNumberSize fields, the destinationAddress buffer and destinationAddressSize fields, and the serviceCenterNumber buffer and serviceCenterNumberSize fields. If the size of the data for any of the buffer fields exceeds the allocated length of the buffer, the end of the data is truncated and this function returns the telErrBufferSize error. Each of the size fields is always updated to contain the complete size of the data intended for the buffer.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsSelectStorage, TelSmsSendMessage
Retrieve a range of submitted messages from the currently selected storage area.
Err TelSmsReadSubmittedMessages(UInt16 iRefnum, TelAppID iAppId, TelSmsReadSubmittedMessagesType *ioParamP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioParamP | A pointer to a TelSmsReadMessagesType structure. |
On input, the first field of this structure specifies the index of the first message to retrieve. Message indexes are zero-based. |
On input, the count field of this structure specifies the allocated size of the submittedsP buffer. Upon return, the count field specifies the actual number of messages that were available, even if that many could not fit into the buffer. |
The submittedsP buffer must contain pointers to TelSmsSubmittedMessageType structures that have been allocated. Each of these structures must be initialized as described for the TelSmsReadSubmittedMessage function. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsReadSubmittedMessagesType structure passed to this function in the ioParamP parameter. |
functionId |
kTelSmsReadSubmittedMessagesMessage |
If the message data or any of the other variable-length data for any of the retrieved messages is larger than the allocated size of its corresponding buffer, the end of the data is truncated, and this function returns the telErrBufferSize error. For more information, see the Comments description for the TelSmsReadSubmittedMessage function.
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsSelectStorage, TelSmsSendMessage
Select a storage area on the phone as the current storage area.
Err TelSmsSelectStorage(UInt16 iRefnum, TelAppID iAppId, UInt8 iStorageId, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
-> ioStorageId | The ID of the storage area. This must be one of the SMS Storage ID Constants. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsGetAvailableStorage, TelSmsGetSelectedStorage
Send a manual acknowledgment of a previously received message. Note that this function is not supported on GSM networks.
Err TelSmsSendManualAcknowledge(UInt16 iRefnum, TelAppID iAppId, TelSmsManualAckType *ioAckP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioAckP | A pointer to a structure of type TelSmsManualAckType. The fields of this structure specify information about the message being acknowledged. |
Upon return, the messageId field is filled in with the ID of the acknowledgment. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsManualAckType structure passed to this function in the ioAckP parameter. |
functionId |
kTelSmsSendManualAcknowledgeMessage |
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
Err TelSmsSendMessage(UInt16 iRefnum, TelAppID iAppId, TelSmsSendMessageType *ioMessageP, UInt16 *ioTransIdP);
-> iRefnum | The telephony manager library reference number. |
-> iAppId | The telephone application attachment identifier for your application. |
<-> ioMessageP | A pointer to a structure of type TelSmsSendMessageType. |
On input, the message field of this structure contains a TelSmsSubmitMessageType with the message to send. You must also allocate and zero at least one TelSmsExtensionType structure for the multi-part information. |
On output, the messageId field of this structure is filled in with the ID that was assigned to the sent message. |
<-> ioTransIdP | Set the value of this parameter to NULL to cause the function to execute synchronously. |
If this parameter is not NULL, the call executes asynchronously. Upon return from this function, this points to the transaction identifier associated with the asynchronous operation. |
Returns errNone if the function was successful or returns an error code if not successful.
The following fields are updated in the TelEventType event that is sent when the operation completes:
returnCode |
errNone upon success or an error code upon failure. |
transId |
The transaction ID of the operation. |
paramP |
Points to the TelSmsSendMessageType structure passed to this function in the ioMessageP parameter. |
functionId |
kTelSmsSendMessageMessage |
You need to make multiple calls to the TelSmsSendMessage function to send your message:
The first call to TelSmsSendMessage does not actually send the message. It computes the number of parts and fills in the multi-part extension structures in the TelSmsSendMessageType structure. Note that you must allocate at least one extension structure, even for single-part messages.
Subsequent calls to TelSmsSendMessage actually send the data.
To send an entire message, you need to call TelSmsSendMessage in a loop. Terminate the loop when an error occurs, or when the byteSend field of the first TelSmsExtensionType structure has the same value as the dataSize field of the TelSmsSendMessageType structure that represents the message. For example:
while (!TelSmsSendMessage(...) && msg.extensionP[0].extension.mp.byteSend != dataSend);
Before using this function, you should verify that it is available by calling the TelIsSmsServiceAvailable macro.
Implemented only if 4.0 New Feature Set is present.
TelSmsSelectStorage, TelCfgSetSmsCenter
|