. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectSMS Xtra
 Communicate with mobile devices from Director and Authorware!

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleMacOS X CompatibleWindows Compatible   

DirectSMS Xtra™ Version 1.0 Documentation

 

Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 2004.
Last updated: August 30th, 2004.

DirectSMS is a cross-platform, easy to use Scripting Xtra for Macromedia Director, Authorware and Shockwave that provides applications with the ability to communicate with mobile devices.

By using DirectSMS Xtra, Director, Authorware and Shockwave applications can easily generate and send short wireless text messages (also known as SMS messages) to cellular phones and pagers throughout the world.

All that is required for the Xtra to send SMS messages is that the computer on which the application is running on would be connected to the Internet. No special hardware or software is required.

DirectXtras is also able to offer a customized version of the Xtra for developers who wish to incorporate SMS receiving capabilities in their applications.

DirectSMS Xtra is Shockwave safe and therefore it can also be used with Shockwave 7 or newer and when safety features in Director are turned on.

An auto downloadable Shockwave safe package of DirectSMS Xtra is also available. It is a compressed, small sized (less than 30K) version of the Xtra, that can be downloaded automatically from a web site to the user's local machine whenever needed, and once installed provides Shockwave applications on the web with the ability to send SMS messages.

DirectSMS Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8, 9 and X.

Installation

Registration

SMS Overview - How it works

Scripting Overview

Using DirectSMS Xtra

Sample Code

Functions Reference

New()
Forget()

smsSend()
smsStatus()
smsDone()

smsAbort()
smsResult()
smsErrorCode()

Sub-accounts functions:

smsGetSubAccounts()
smsCreateSubAccount()
smsDeleteSubAccount()
smsPromoteSubAccount()
smsGetSubAccount()
smsGetParentAccount()
smsTransferCreditsTo()
smsTransferCreditsFrom()

Error Codes

History

 

Installation

DirectSMS Xtra has an authoring version, a run time version, a Shockwave
version, and an auto downloadable Shockwave safe package. The trial
version only includes the authoring version.

The authoring version is used by Director and/or Authorware authoring environment while developing your movie/presentation. It should be placed in your Director and/or Authorware "Xtras" folder.

The run time version is used when running your movie/presentation as a stand-alone application. It should be placed in a folder named "Xtras" that is inside the folder that contains the host projector/package. Alternatively, the run time version can be bundled in projectors/packages (in a similar way you bundle other Director\Authorware files).

The run time version is also used with the Authorware web player and can be bundled in the web package. When creating web packages in Authorware,  please note that by default, Authorware will attempt to bundle the authoring version of the Xtra. You'd have to modify the application 'Publish Settings' in order to instruct Authorware to bundle the run time version instead of the authoring version.

The Shockwave safe version is used by Shockwave for Director, and should be placed in the appropriate Shockwave 'Xtras' folder. It is highly recommended not to distribute and manually install the Shockwave safe version to the Shockwave 'Xtras' folder as there is no reliable way to do so. The Shockwave safe version is provided for testing purposes only. Applications should use the auto downloadable and auto installable Shockwave safe package instead.

The auto downloadable Shockwave safe package is used by Shockwave for Director. The package should be uploaded to your server from which it will automatically get downloaded and installed by your Shockwave movie, if needed.

Please note that Director requires that both the Windows and MacOS versions of the package would be uploaded to your server even if you're only using the Xtra on one platform.

Once you have decided the location on your server where the auto
downloadable packages will be placed, you should modify the "xtrainfo.txt"
file in the Director 7 or above folder accordingly. For example, if you uploaded
the downloadable package to "http://www.myserver.com/packs" you
should add the following line to "xtrainfo.txt".

[#namePPC:"DirectSMS", #nameW32:"DirectSMS.x32", #package:"http://www.myserver.com/packs/DirectSMS"]

Note that the above entry should consist of a single line in the "xtrainfo.txt" file.

Finally, add a reference to the auto downloadable package in your movie.
Open a movie that uses the DirectSMS Xtra. From the
Modify->Movie->Xtras dialog in Director, select the DirectSMS Xtra in
the list of Xtras. The "Download if needed" check box should now be
enabled. (If it's not enabled, make sure the filename in "xtrainfo.txt" matches
the actual filename of the Xtra.) Click on the check box and Director will load
information from the package file for each platform and add it to the current
movie.

IMPORTANT: The authoring, run time and Shockwave versions can not
coexist in the same "Xtras" folder, so be sure to place the appropriate version
in the appropriate folder.

 

Registration

DirectSMS Xtra is a commercial product. 

Basically, there are 3 types of licenses: Single, Site and Corporate.

Single License: Entitles an organization to receive one copy of the licensed Xtra(s) which can only be used by a single developer on a single computer at any one time.

Site License: Entitles an organization to receive one copy of the licensed Xtra(s) which can be used by any number of developers on any number of workstations within one site.

Corporate License: Entitles an organization to receive one copy of the
licensed Xtra(s) which can be used by any number of developers on any
number of workstations within the entire corporation (multiple sites).

Important Notes:

  • A copy of the licensed Xtra includes the Authoring and freely distributable Runtime versions.
  • If you intend to distribute your application on both platforms (Windows and MacOS), or if you author your application on one platform and intend to deliver it on the other platform, you'd have to license both the Windows and MacOS versions of the Xtra.
  • Qualification for free and discounted upgrades and updates will be provided based on the registered e-mail address.
  • All licenses now include the Shockwave safe version of the Xtra along with an auto-downloadable Shockwave safe package which can be used with Shockwave movies on the web.
  • Single and Site licenses include free future upgrades and updates for minor revisions of the licensed Xtra(s), while Corporate license includes free future upgrades and updates for both major and minor revisions of the licensed Xtra(s).

Once you have licensed DirectSMS Xtra, you will be given a serial number. In addition, a DirectSMS account will be created for you and you will be provided with the account ID and password.

Your DirectSMS account ID and password as well as your DirectSMS Xtra serial number should be passed to the New() function when creating the DirectSMS Xtra instance in order to unlock the trial limitations. Once the Xtra is unlocked, trial warnings will no longer be presented, there will be no other limitations and the run-time and Shockwave versions of the Xtra will become activated.

Be sure to protect the call to New() so that your DirectSMS account ID and password as well as your DirectSMS Xtra serial number would not become exposed to others. This can be done in a similar way you protect the rest of your application source code. If you intend to distribute your application with open source code then pass New() an empty string as your DirectSMS account ID and password and the number 0 as your serial number. This will switch the Xtra to a trial mode and you can instruct developers to change the values with their account ID, password and serial number. Alternatively, you can protect just the appropriate New() calls in your code.

The New() function should be called before any of the other Xtra functions are called. 

You can freely distribute the run time version and Shockwave safe package of DirectSMS Xtra with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

Note that if your Shockwave movie needs to run on both Windows and MacOS, you'd need to obtain a license for both the Windows and MacOS versions of the Xtra, in order to obtain both the Windows and MacOS Shockwave safe versions and their auto-downloadable Shockwave safe packages, along with serial numbers to activate them.

 

SMS Overview - How it works

DirectSMS Xtra communicates with mobile devices through a Wireless Messaging Network over the Internet. As a result, the only requirement for communicating with mobile devices is that the machine on which the application is running on would be connected to the Internet.

When sending out an SMS message, the Xtra connects and delivers the SMS message to a Wireless Messaging Network. It is then the network responsibility to deliver the message to the recipient mobile device. Therefore, after transmitting the message to the network, applications do not need to take further actions for the message to be delivered, though they should insure that the message was properly queued for delivery and query the network for the message status. 

Sending out SMS messages involves in a small fee for each SMS that is being sent. As a result, developers who use the Xtra need also sign up for a DirectSMS account with DirectXtras, and fill it with SMS credits. Each time an application sends out SMS messages, the appropriate amount of SMS credits would be deducted from the developer account.

DirectSMS Xtra relays on the Simplewire™ Wireless Messaging Network. Simplewire’s network is the conduit through which DirectSMS Xtra is able to
reach wireless users throughout the world. It is one of the largest and most reliable wireless messaging networks in the world, offering a global backbone comprised of industry-leading, high performance architecture. The network currently maintains connections to over 300 network operators in 118 countries worldwide, and is constantly growing.

A complete list of worldwide networks supported by the Simplewire Wireless Messaging Network, including the number of message credits that will be decremented from your account for each message that is sent, please refer to:

 http://www.simplewire.com/developers/knowledge/reference/coverage/

In some cases applications may want to transfer the SMS cost to their end users, or limit the amount of SMS messages that can be sent by each user. For these reasons, the Xtra also provides sub accounts feature. The sub accounts feature allows developers to create sub accounts of their DirectSMS account, transfer SMS credits from their parent DirectSMS account to its sub accounts and send SMS messages from a sub account rather than the parent DirectSMS account. Using this feature, applications can create a sub account for each end user who wish to send SMS messages, and fill it with SMS credits as necessary.

DirectSMS Xtra can not receive SMS messages. Replies to the SMS messages sent by the Xtra would go to the callback number which applications specify when sending the SMS messages.

In order to receive SMS messages, developers need to hold and maintain one or more cell phone lines which would accept SMS replies and forward them back to the application through the Internet. The number of cell phone lines needed mainly depends on how many instances of the application may send SMS messages simultaneously, to insure that the appropriate reply would go to the particular application instance which sent the SMS message.

We are able to provide custom solutions for developers who wish to incorporate SMS receiving capabilities in their applications. For more details, please contact us at info@directxtras.com and provide detailed information on your application and the SMS receiving capability it needs.

 

Scripting Overview

DirectSMS Xtra adds functions to Director and Authorware which provide applications with the ability to communicate with mobile devices. The Xtra functions are divided into two categories, asynchronous and synchronous.

Synchronous functions return control to Director/Authorware as soon as they
complete their task. They return an error code indicating whether their task
was completed successfully. All of the synchronous DirectSMS functions
return immediately, as they only retrieve information such as error codes,
function results, transfer status, etc.

Asynchronous functions return control to Director/Authorware immediately,
while continuing to perform their task in the background. They return an error
code indicating whether their task was started successfully. Asynchronous functions might fail to create or start the background task if there is not enough free memory available, an invalid parameter was passed or another background task is in progress.

As an example, smsSend() function is asynchronous, allowing your
application to send an SMS while at the same time perform other tasks, such as
playing an animation indicating that an SMS is being sent, or calling other
DirectSMS synchronous functions, such as smsDone(), to track down the transmission status. smsDone() is a synchronous function which immediately checks and returns whether a background task, that has been created by an asynchronous function, is still taking place.

Each instance of DirectSMS Xtra can manage one background task at a time. In order to have multiple background tasks at the same time, create multiple instances of DirectSMS Xtra and work with them simultaneously.

Once DirectSMS asynchronous function succeeds to create a background
task, you should frequently call smsDone() to check its status. When the
background task is completed, call smsErrorCode() to check whether the
task was completed successfully, and smsResult() to obtain further
information about the completed task.

Using DirectSMS Xtra

Following are step by step instructions on how an application can use the Xtra to send SMS messages.

Step 1 - Create a new instance of DirectSMS Xtra and store it for a later use.

Applications have to store the DirectSMS instance in a variable so that they can later on pass it as the first parameter to the other Xtra functions.

Director Example -

Set SMS = new (Xtra "DirectSMS", "MyAccount", "MyPassword", 0)

Sample Code for Authorware :

SMS:=NewObject("DirectSMS", "MyAccount", "MyPassword", 0)

JavaScript Sample Code for Director :

 var SMS = new xtra("DirectSMS", "", "", 0)

In the above example, "MyAccount" is the DirectSMS account ID, "MyPassword" is the DirectSMS account password and 0 is the DirectSMS Xtra serial number. If you're using the trial version, the DirectSMS account ID and password parameters should be set to an empty string and the serial number parameter should be set to 0.

Step 2 - Send the SMS

Lingo Sample Code for Director :

Set Error = smsSend (SMS, "+14155058249", "+11005112396", "This is the message", "From me")

Sample Code for Authorware :

Error:=CallObject (SMS, "smsSend", "+14155058249", "+11005112396", "This is the message", "From me")

JavaScript Sample Code for Director :

 var Error = SMS.smsSend ("+11005112396", "+11005112396", "This is the message", "From me")

In the above example, "+14155058249" is the sender (callback) mobile number in an international format and "+11005112396" is the recipient mobile number in an international format.

After calling smsSend() applications should check the value of variable 'Error'. If it
is zero, then the background task which suppose to send the SMS has been created successfully and therefore the application can move on to the next step. Otherwise, the value is an error code indicating the error that has occurred.

Step 3 - Frequently call smsDone() to check the status of the SMS which is being
sent in the background.

Lingo Sample Code for Director :

Set Status = smsDone(SMS)

Sample Code for Authorware :

Status:=CallObject (SMS, "smsDone")

JavaScript Sample Code for Director :

var Status = SMS.smsDone()

As soon as smsDone() returns TRUE, call smsErrorCode() to check whether the SMS was sent successfully.

If smsErrorCode() returns 0 (zero), that means that the SMS was sent successfully to the Wireless Messaging Network and the application should move to the next step, otherwise the returned value is a number indicating the error that has occurred.

Step 4 - Obtain information about the SMS

At this point the SMS has been successfully sent to the Wireless Messaging Network. However, that does not yet guarantee that the SMS has been successfully delivered to the recipient mobile device carrier. In order to query the Wireless Messaging Network for the status of the SMS that is being delivered, applications should first call smsResult() to obtain the SMS ticket ID. The SMS ticket ID is a unique tracking number that allows applications to track the status of a particular SMS. smsResult() can also be used to find out how many SMS credits will be deducted from the DirectSMS account upon completion of the SMS delivery.

Lingo Sample Code for Director :

Set TicketID = smsResult(SMS, 1)
Set SMSPrice = smsResult(SMS, 2)

Sample Code for Authorware :

TicketID:=CallObject (SMS, "smsResult", 1)
SMSPrice:=CallObject (SMS, "smsResult", 2)

JavaScript Sample Code for Director :

var TicketID = SMS.smsResult(1)
var SMSPrice = SMS.smsResult(2)

Step 5 - Check the status of the SMS

Using the SMS ticket ID, which was obtained in the previous step, applications can now query the Wireless Messaging Network for the status of the SMS using the smsStatus() function.

Lingo Sample Code for Director :

Set Error = smsStatus(SMS, TicketID)

Sample Code for Authorware :

Error:=CallObject (SMS, "smsStatus", TicketID)

JavaScript Sample Code for Director :

Set Error =
SMS.smsStatus( TicketID)
 

smsStatus() is an asynchronous function (similar to smsSend()). It creates a background task which queries for the SMS status, and therefore after calling smsStatus(), applications should check the value of variable 'Error'. If it is zero, then the background task that suppose to check the SMS status has been created successfully and therefore the application can move on and wait for smsDone() to return true. Otherwise, 'Error' is an error code indicating the error that has occurred.

As soon as smsDone() returns TRUE, applications should call smsErrorCode() to check whether the SMS status was retrieved successfully.

If smsErrorCode() returns 0 (zero), that means that the SMS status was retrieved successfully from the Wireless Messaging Network and the application should then call smsResult() to obtain the SMS status code and description.

Lingo Sample Code for Director :

Set StatusCode = smsResult(SMS, 3)
Set StatusDescription = smsResult(SMS, 4)

Sample Code for Authorware :

StatusCode:=CallObject (SMS, "smsResult", 3)
StatusDescription:=CallObject (SMS, "smsResult", 4)

JavaScript Sample Code for Director :

Set StatusCode =
SMS.smsResult(3)
Set StatusDescription =
SMS.smsResult( 4)

'StatusCode' variable now contains the status code of the SMS.

A status code of 1, 2, 3 or 5 means that the SMS is still being delivered and that additional queries should be made later.

A status code of 0 means that the SMS has been successfully sent to the carrier, and a status code of 4 means that the SMS has been successfully delivered. If the status code is 0 or 4, the SMS has been successfully sent and no further queries should be made.

Any other status code indicates an error that has occurred during the SMS delivery. No further queries should be made if an error occurs.

Step 6 -

If you want to send another SMS, jump back to step 2, otherwise delete the
DirectSMS instance that you've created in step 1.

Lingo Sample Code for Director : Set SMS=0

Sample Code for Authorware : DeleteObject(SMS)

JavaScript Sample Code for Director : var SMS=0

The following section summary all steps and includes a complete sample code for sending an SMS.

Sample Code

This section includes a sample code for Director and Authorware. The sample code is based on the 6 implementation steps which were described in the previous section.

Important Notes: For the code to work properly, you'd need to provide New() with your DirectSMS account ID and password as well as your DirectSMS Xtra serial number. Otherwise, the Xtra will work in an evaluation mode, which can only send a limited number of SMS messages and is only functional for 30 days.

You'd also need to modify the sender and recipient phone numbers.

Please also note that the following code waits in a repeat loop for smsDone() to return true. We're using a repeat loop here for simplicity reasons. However, Director and Authorware ignore events and halt playback while in a repeat loop. As a result the application may appear to be hung while sending the SMS and it would take more time for the SMS to be sent. Therefore it is recommended to wait for smsDone() to return true while processing events and not in an empty repeat loop as we're demonstrating here.

Lingo Sample Code for Director :

Sample Code for Authorware :

 

JavaScript Sample Code for Director :

Functions Reference

 

Director: New ( Xtra "DirectSMS", string AccountID, string AccountPassword, integer SerialNumber )

Authorware: NewObject ( "DirectSMS", string AccountID, string AccountPassword, integer SerialNumber )

Creates a new DirectSMS Xtra instance.

The returned value is a new instance of DirectSMS Xtra.

Parameters :

AccountID : DirectSMS account ID. The account must be active and filled with SMS credits. For more details on DirectSMS accounts please refer to the SMS overview section. If you are using the trial version, pass an empty string.

AccountPassword : DirectSMS account password. If you are using the trial version, pass an empty string.

SerialNumber : DirectSMS Xtra Serial Number. If you are using the trial version, pass the number 0.

Returns : DirectSMS instance.

Remarks : This function is synchronus.

 

Director: Forget ( object me )

Authorware: DeleteObject ( object me )

 

Deletes a DirectSMS Xtra instance.

Parameter :

object me : DirectSMS Instance.

Returns : None.

Remarks : This function is synchronus.

Director applications can also delete the DirectSMS Xtra instance by setting it to zero.

Since this function is synchronous, it might not return immediately if you dispose the instance while a background task is in progress (it calls smsAbort() internally, in synchronous mode, and times out after 5 seconds).

You can get around the delay by calling smsAbort() before deleting the instance, to abort the operation in progress properly, as smsAbort() is asynchronous.

 

smsSend ( object me, string CallbackNumber, string ToPhoneNumber, string Message, string From )

Generates and sends an SMS.

The function initiates a background task for sending an SMS to the Wireless Messaging Network.

If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed. Finally, if no error has occurred, the SMS has been successfully sent to the Wireless Messaging Network and applications can call smsResult() to obtain the SMS ticket ID and cost.

Note that a successful delivery of the SMS message to the Wireless Messaging Network does not yet guarantee that the SMS has been successfully delivered to the recipient mobile device carrier. In order to query the Wireless Messaging Network for the status of the SMS that is being delivered, applications should call smsStatus() and provide it with the SMS ticket ID.

Parameters :

object me : DirectSMS Instance.

CallbackNumber : The SMS callback number. This is the number that gets dialed when a recipient press 'talk' on their device after viewing a message or when replying to a message.

ToPhoneNumber : The mobile phone number of the intended recipient.

Message : The content of the message. The length limit of an SMS message is usually 160 characters though some carriers may offer higher limits.

From : The name of the message sender. This parameter is optional and may behave differently among carriers. It mostly applies in the U.S. where several carriers support a 'From' entry in SMS messages. In some cases this parameter can be set to an email address so the recipient could hit reply on their phone to send a reply to the specified email account.

Returns : If the function succeeds it returns zero, otherwise an error code is returned.

Remarks : This function is asynchronus.

The recipient and callback phone numbers should be specified in an international format. The international phone number format is specified by the "+" character, followed by the country code, followed by the national number. For example, the international format of the phone number (415)-5058249 in the U.S. (country code 1) is "+14155058249".

If you specify a phone number in a non international format, it would be assumed to be a phone number in the U.S.

The SMS time stamp is set to GMT+1 and can not be set.

 

smsStatus ( object me, string TicketID )

Checks the status of an SMS.

The function initiates a background task for checking the transmission status of an SMS specified by the TicketID parameter. If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed. Finally, if no error has occurred, applications can call smsResult() to obtain the SMS status.

Parameters :

object me : DirectSMS Instance.

TicketID : A string indicating the ticket ID of the SMS whose status is about to be checked. The ticket ID is returned by the smsResult() function after a successful transmission of the SMS to the Wireless Messaging Network.

Returns : If the function succeeds it returns zero, otherwise an error code is returned.

Remarks : This function is asynchronus.

 

smsDone ( object me )

Returns TRUE if the last asynchronous task has been completed and FALSE if not.

If the function returns TRUE, applications should call smsErrorCode() to check whether the task was completed successfully.

Parameter :

object me : DirectSMS Instance.

Returns : TRUE or FALSE.

Remarks : This function is synchronus.

 

smsAbort ( object me )

Aborts the current asynchronous task and any associated transfer of data.

Parameter :

object me : DirectSMS Instance.

Returns : 0

Remarks : This function is Asynchronus.

Aborted tasks may be partially completed.

For example, aborting smsSend() may result in the SMS being sent but without returning the SMS ticket ID.

 

smsResult ( object me, integer ResultType )

Returns information from the last completed task.

The function should be called after smsDone() and smsErrorCode() indicate that the task is completed successfully and before another background task starts.

Parameters :

object me : DirectSMS Instance.

ResultType : The type of information to obtain. This parameter can be set to one of the following values:

0 - Returns a human readable string describing the error message which has occurred while communicating with the Wireless Messaging Network. The error message is available after smsSend() or smsStatus() completes their background task and is equivalent to the error code returned by smsErrorCode().

1 - Returns a string indicating the SMS ticket ID. The ticket ID is available after smsSend() successfully sends the SMS to the Wireless Messaging Network.

2 - Returns an integer indicating the number of SMS credits it cost to send the SMS. The SMS cost is available after smsSend() successfully sends the SMS to the Wireless Messaging Network.

3 - Returns an integer indicating the SMS transmission status. The transmission status is available after smsStatus() successfully obtains it from the Wireless Messaging Network.

A status code of 1, 2, 3 or 5 means that the SMS is still being delivered and that additional queries should be made later.

A status code of 0 means that the SMS has been successfully sent to the carrier, and a status code of 4 means that the SMS has been successfully delivered. If the status code is 0 or 4, the SMS has been successfully sent and no further queries should be made.

The fact that the carrier received the message doesn't necessarily mean that the phone got the message. With many carriers, if the user doesn't have text messaging enabled, you'll still get a success code even though the target will never get the message. However, for the vast majority of messages sent out, status codes 0 and 4 indicate a successful hit.

Any other status code indicates an error that has occurred during the SMS delivery. No further queries should be made if an error occurs.

4 - Returns a human readable string describing the SMS transmission status. The transmission status is equivalent to the one described in the previous option # 3, except that the returned value is a human readable string rather than an integer. The transmission status is available after smsStatus() successfully obtains it from the Wireless Messaging Network.

5 - Returns a list of strings indicating sub accounts information. The list is available after smsGetSubAccounts(), smsCreateSubAccount(), smsGetSubAccount() or smsGetParentAccount() completes its task successfully.

Returns : A string, an integer or a list containing the requested information.

Remarks : This function is synchronus.

 

smsErrorCode ( object me )

Returns an error code indicating the last error that has occurred.
 

Parameter :

object me : DirectSMS Instance.

Returns : Error code.

Remarks : This function is synchronus.

 

smsGetSubAccounts ( object me )

Returns the sub accounts of the parent DirectSMS account.

The function initiates a background task for obtaining a list of all the sub accounts of the parent DirectSMS account. The parent DirectSMS account is the account specified to the New() function on instance creation.

If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, applications can call smsResult() to obtain the sub accounts list. smsResult() would then return a list of strings, where each item in the returned list is a string indicating the sub account ID.

Parameter :

object me : DirectSMS Instance.

Returns : Error code.

Remarks : This function is asynchronus.

smsCreateSubAccount ( object me, string FirstName, string LastName, string Email, string Address1, string Address2, string City, string Region, string Country, string PostalCode )

Creates a new sub account.

The function initiates a background task for creating a new sub account of the parent DirectSMS account. The parent DirectSMS account is the account specified to the New() function on instance creation. If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, applications can call smsResult() to obtain the newly created sub account ID and password. smsResult() would then return a list of two strings. The first string in the list indicates the newly created sub account ID, and the second string in the list indicates the newly created sub account password.

Parameters :

object me : DirectSMS Instance.
FirstName : The account holder's first name. This parameter must not be set to an empty string.
LastName : The account holder's last name. This parameter must not be set to an empty string.
Email : The account holder's e-mail address. This parameter must be a valid e-mail address.
Address1 :
The account holder's address, part 1. This parameter may be set to an empty string, see 'Remarks'.
Address2 : The account holder's address, part 2. This parameter may be set to an empty string.
City : The account holder's City. This parameter may be set to an empty string, see 'Remarks'.
Region :
The account holder's Region. This parameter may be set to an empty string, see 'Remarks'.
Country : 2 letters abbreviation specifying the account holder's Country. This parameter may be set to an empty string, see 'Remarks'.
PostalCode : The account holder's postal code. This parameter may be set to an empty string, see 'Remarks'.

Returns : Error code.

Remarks : This function is asynchronus.

The Address1, Address2, City, Region, Country and PostalCode parameters may be set to an empty string, in which case the newly created sub account would not include address information. However, if either one of the address parameters is specified, all the other must be specified as well, except Address2, which is optional.

The Country parameter, if specified, must be one of the following ISO 2-letter country codes:

AD - Andorra
AE - United Arab Emirates
AF - Afghanistan
AG - Antigua and Barbuda
AI - Anguilla
AL - Albania
AM - Armenia
AN - Netherlands Antilles
AO - Angola
AQ - Antarctica
AR - Argentina
AS - American Samoa
AT - Austria
AU - Australia
AW - Aruba
AZ - Azerbaijan
BA - Bosnia and Herzegovina
BB - Barbados
BD - Bangladesh
BE - Belgium
BF - Burkina Faso
BG - Bulgaria
BH - Bahrain
BI - Burundi
BJ - Benin
BM - Bermuda
BN - Brunei Darussalam
BO - Bolivia
BR - Brazil
BS - Bahamas
BT - Bhutan
BV - Bouvet Island
BW - Botswana
BY - Belarus
BZ - Belize
CA - Canada
CC - Cocos (Keeling) Islands
CD - Congo, the Democratic Republic of the
CF - Central African Republic
CG - Congo
CH - Switzerland
CI - Cote d'Ivoire
CK - Cook Islands
CL - Chile
CM - Cameroon
CN - China
CO - Colombia
CR - Costa Rica
CU - Cuba
CV - Cape Verde
CX - Christmas Island
CY - Cyprus
CZ - Czech Republic
DE - Germany
DJ - Djibouti
DK - Denmark
DM - Dominica
DO - Dominican Republic
DZ - Algeria
EC - Ecuador
EE - Estonia
EG - Egypt
EH - Western Sahara
ER - Eritrea
ES - Spain
ET - Ethiopia
FI - Finland
FJ - Fiji
FK - Falkland Islands (Malvinas)
FM - Micronesia, Federated States of
FO - Faroe Islands
FR - France
GA - Gabon
GD - Grenada
GE - Georgia
GF - French Guiana
GH - Ghana
GI - Gibraltar
GL - Greenland
GM - Gambia
GN - Guinea
GP - Guadeloupe
GQ - Equatorial Guinea
GR - Greece
GS - South Georgia and the South Sandwich Islands
GT - Guatemala
GU - Guam
GW - Guinea-Bissau
GY - Guyana
HK - Hong Kong
HM - Heard Island and McDonald Islands
HN - Honduras
HR - Croatia
HT - Haiti
HU - Hungary
ID - Indonesia
IE - Ireland
IL - Israel
IN - India
IO - British Indian Ocean Territory
IQ - Iraq
IR - Iran, Islamic Republic of
IS - Iceland
IT - Italy
JM - Jamaica
JO - Jordan
JP - Japan
KE - Kenya
KG - Kyrgyzstan
KH - Cambodia
KI - Kiribati
KM - Comoros
KN - Saint Kitts and Nevis
KP - Korea, Democratic People's Republic of
KR - Korea, Republic of
KW - Kuwait
KY - Cayman Islands
KZ - Kazakstan
LA - Lao People's Democratic Republic
LB - Lebanon
LC - Saint Lucia
LI - Liechtenstein
LK - Sri Lanka
LR - Liberia
LS - Lesotho
LT - Lithuania
LU - Luxembourg
LV - Latvia
LY - Libyan Arab Jamahiriya
MA - Morocco
MC - Monaco
MD - Moldova, Republic of
MG - Madagascar
MH - Marshall Islands
MK - Macedonia
ML - Mali
MM - Myanmar
MN - Mongolia
MO - Macau
MP - Northern Mariana Islands
MQ - Martinique
MR - Mauritania
MS - Montserrat
MT - Malta
MU - Mauritius
MV - Maldives
MW - Malawi
MX - Mexico
MY - Malaysia
MZ - Mozambique
NA - Namibia
NC - New Caledonia
NE - Niger
NF - Norfolk Island
NG - Nigeria
NI - Nicaragua
NL - Netherlands
NO - Norway
NP - Nepal
NR - Nauru
NU - Niue
NZ - New Zealand
OM - Oman
PA - Panama
PE - Peru
PF - French Polynesia
PG - Papua New Guinea
PH - Philippines
PK - Pakistan
PL - Poland
PM - Saint Pierre and Miquelon
PN - Pitcairn
PR - Puerto Rico
PT - Portugal
PW - Palau
PY - Paraguay
QA - Qatar
RE - RÉunion
RO - Romania
RU - Russian Federation
RW - Rwanda
SA - Saudi Arabia
SB - Solomon Islands
SC - Seychelles
SD - Sudan
SE - Sweden
SG - Singapore
SH - Saint Helena
SI - Slovenia
SJ - Svalbard and Jan Mayen
SK - Slovakia
SL - Sierra Leone
SM - San Marino
SN - Senegal
SO - Somalia
SR - Suriname
ST - Sao Tome and Principe
SV - El Salvador
SY - Syrian Arab Republic
SZ - Swaziland
TC - Turks and Caicos Islands
TD - Chad
TF - French Southern Territories
TG - Togo
TH - Thailand
TJ - Tajikistan
TK - Tokelau
TM - Turkmenistan
TN - Tunisia
TO - Tonga
TP - East Timor
TR - Turkey
TT - Trinidad and Tobago
TV - Tuvalu
TW - Taiwan, Province of China
TZ - Tanzania, United Republic of
UA - Ukraine
UG - Uganda
UK - United Kingdom
UM - United States Minor Outlying Islands
US - United States
UY - Uruguay
UZ - Uzbekistan
VA - Holy See (Vatican City State)
VC - Saint Vincent and the Grenadines
VE - Venezuela
VG - Virgin Islands, British
VI - United States Virgin Islands
VN - Vietnam
VU - Vanuatu
WF - Wallis and Futuna
WS - Samoa
YE - Yemen
YT - Mayotte
YU - Yugoslavia
ZA - South Africa
ZM - Zambia
ZW - Zimbabwe

 

 

 

smsDeleteSubAccount ( object me, string SubAccount )

Deletes the specified sub account.

The function initiates a background task for deleting a sub account of the parent DirectSMS account. The parent DirectSMS account is the account specified to the New() function on instance creation. If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, the specified sub account has been deleted.

Parameters :

object me : DirectSMS Instance.
SubAccount : The sub account ID.

Returns : Error code.

Remarks : This function is asynchronus.

 

smsPromoteSubAccount ( object me, string SubAccount )

Promotes the sub account specified by SubAccount to a parent account.

By promoting a sub account to a parent application can create sub accounts of the promoted account.

The function initiates a background task for promoting a sub account of the parent DirectSMS account. The parent DirectSMS account is the account specified to the New() function on instance creation. If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, the specified sub account has been promoted successfully.

Parameters :

object me : DirectSMS Instance.
SubAccount : The sub account ID.

Returns : Error code.

Remarks : This function is asynchronus.

 

smsGetSubAccount ( object me, string SubAccount )

Retrieves information on the specified sub account.

The function initiates a background task for retrieving information on the specified sub account of the parent DirectSMS account. The parent DirectSMS account is the account specified to the New() function on instance creation. The sub account is specified by the SubAccount parameter.

If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, applications can call smsResult() to obtain the sub account information. smsResult() would then return a list of strings, indicating the sub account first name, last name, e-mail address, address 1, address 2, city, region, country, postal code, available SMS credits and account password (in this order).

Parameters :

object me : DirectSMS Instance.
SubAccount : The sub account ID.

Returns : Error code.

Remarks : This function is asynchronus.

 

smsGetParentAccount ( object me )

Retrieves information on the parent sub account.

The function initiates a background task for retrieving information on the parent DirectSMS account. The parent DirectSMS account is the account specified to the New() function on instance creation.

If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, applications can call smsResult() to obtain the parent account information. smsResult() would then return a list of strings. The first item in the returned string indicates the available credits. The second item in the returned list is "1" if the account can have sub accounts and "0" otherwise.

Parameter :

object me : DirectSMS Instance.

Returns : Error code.

Remarks : This function is asynchronus.

 

smsTransferCreditsTo ( object me, string SubAccount, integer NumOfCredits )

Transfers credits from the DirectSMS parent account to the specified sub account.

The function initiates a background task for transferring SMS credits from the DirectSMS parent account to one of its sub accounts which is specified by the SubAccount parameter. The parent DirectSMS account is the account specified to the New() function on instance creation.

If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, the SMS credits has been transferred.

Parameters :

object me : DirectSMS Instance.
SubAccount : The sub account ID.
NumOfCredits : The number of credits to transfer.

Returns : Error code.

Remarks : This function is asynchronus.

 

smsTransferCreditsFrom ( object me, string SubAccount, integer NumOfCredits )

Transfers credits from the specified sub account to its DirectSMS parent account.

The function initiates a background task for transferring SMS credits from the sub account which is specified by the SubAccount parameter, to its DirectSMS parent account. The parent DirectSMS account is the account specified to the New() function on instance creation.

If the function succeeds it returns 0 (zero), indicating that the background task has been created successfully. Applications should then frequently call smsDone() to check whether the task is completed. As soon as smsDone() returns true, indicating that the task is completed, applications should call smsErrorCode() to check whether the task has failed.

Finally, if no error has occurred, the SMS credits has been transferred.

Parameters :

object me : DirectSMS Instance.
SubAccount : The sub account ID.
NumOfCredits : The number of credits to transfer.

Returns : Error code.

Remarks : This function is asynchronus.

 

Error Codes

 

Wireless Messaging Network Status and Error Codes:

Status Codes:

0 - Message successfully sent to carrier.
1 - Processing request.
2 - Message successfully queued.
3 - Message buffered with carrier and waiting for delivery response.
4 - Message successfully delivered.
5 - Message transferred to carrier and waiting for buffered response.

Error Codes:

301 - Only one top level request element is permitted.
302 - The xml document could not be validated.
303 - The required version attribute of the request element was not found in the request.
304 - The required protocol attribute of the request element was not found in the request.
305 - The required type attribute of the request element was not found in the request.
306 - The xml parameter for rpc.html cannot be empty.
307 - The request was an ill-formed xml document.
310 - If the force option is going to be set, it can only be set to one or zero.
311 - If the method option is going to be set, it can only be set to 'synch' or 'asynch'.
321 - Invalid request version.
322 - Invalid request protocol.
330 - Invalid number of page elements.
331 - The message alias was invalid.
332 - The message alias has not yet been validated.
340 - Page element requires a message service id attribute.
341 - The message service id does not exist.
342 - A message service id is required.
343 - The message service id is discontinued.
344 - The message service id is beta.
345 - Unable to determine carrier id from pin.
346 - Message destination country code currently not supported.
349 - Message pin contains non-numeric characters.
350 - A message pin is required.
351 - The message pin is not long enough.
352 - The message pin is too long.
353 - Message text is required.
354 - Message text is not long enough.
355 - Message text is too long.
356 - Message from is required.
357 - Message from is not long enough.
358 - Message from is too long.
359 - Message callback is required.
360 - Message callback is not long enough.
361 - Message callback is too long.
362 - Message callback contains non-numeric characters.
380 - Invalid data coding scheme.
381 - Invalid characters used with selected data coding scheme.
385 - Invalid or unsupported ringtone format.
386 - Invalid or unsupported image format.
387 - Must provide a valid phone type to send images or ringtones.
388 - Smart messaging is not supported for this carrier.
389 - A valid image type must be specified.
390 - Must provide numeric country/network codes.
391 - Must provide ringtone data.
392 - Must provide Image data.
393 - Must provide at least a screensaver or a ringtone to send a profile.
394 - Invalid option type for the phone specified.
400 - General error occurred while delivering the message to the carrier.
401 - General error occurred while delivering the message to the carrier.
410 - Message recipient does not subscribe to wireless messaging service with destination carrier.
411 - Message recipient does not subscribe to wireless messaging service with destination carrier.
420 - Invalid subscriber id or subscriber password.
430 - Message delivery not permitted to destination carrier without a valid subscriber id.
450 - Message account limit exceeded.
460 - Subscriber id not found within network.
500 - Carrier service temporarily unavailable.
501 - Carrier unknown subscriber.
502 - Carrier network time-out.
503 - Carrier facility not provided.
504 - Carrier call barred.
505 - Carrier operation barred.
506 - Carrier SC congestion.
507 - Carrier facility not supported.
508 - Carrier absent subscriber.
509 - Carrier delivery fail.
510 - Carrier protocol error.
511 - Carrier MS not equipped.
512 - Carrier unknown SC.
513 - Carrier illegal MS.
514 - Carrier MS not a subscriber.
515 - Carrier error in MS.
516 - Carrier SMS lower layer not provisioned.
517 - Carrier system fail.
518 - Carrier PLMN system failure.
519 - Carrier HLR system failure.
520 - Carrier VLR system faillure.
521 - Carrier previous VLR system failure.
522 - Carrier controlling MSC system failure.
523 - Carrier VMSC system failure.
524 - Carrier EIR system failure.
525 - Carrier system failure.
526 - Carrier unexpected data value.
527 - Carrier error in address service center.
528 - Carrier invalid absolute validity period.
529 - Carrier short message exceeds maximum.
530 - Carrier unable to unpack GSM message.
531 - Carrier unable to convert to IA5 alphabet.
532 - Carrier invalid validity period format.
533 - Carrier invalid destination address.
534 - Carrier duplicate message submit.
535 - Carrier invalid message type indicator.
600 - Carrier checksum error.
601 - Carrier syntax error.
602 - Carrier operation not supported by system.
603 - Carrier call barring active.
604 - Pin is invalid.
605 - Carrier authentication failure.
606 - Carrier legitimization for all calls failure.
607 - GA not valid.
608 - Repetition is not allowed.
609 - Legitimization code for repetition failure.
610 - Priority call is not allowed.
611 - Legitimization for priority call failure.
612 - Urgent message not allowed.
613 - Legitimization code for urgent message not allowed.
614 - Reverse charging is not allowed.
615 - Legitimization code for reverse charging is not allowed.
616 - Deferred delivery is not allowed.
617 - New AC is not allowed.
618 - New legitimization code is not allowed.
619 - Standard text is not valid.
620 - Time period is not valid.
621 - Message type not supported by system.
622 - Requested standard text is not valid.
623 - Message not found.
624 - Subscriber hang-up.
625 - RPID already in use.
626 - Delivery in progress.
627 - Message forwarded.
700 - Invalid number of ticket elements in request.
701 - Message ticket id is required.
710 - Invalid ticket id format.
711 - Ticket id does not exist within the network.
712 - Invalid ticket id since it was null.
800 - Invalid number of service elements in request.
801 - General error while retrieving the service list.
802 - Service id is required.
803 - Invalid service id since it was null.
810 - Failed message delivery.
1000 - General error occurred while processing request.
2001 - Invalid subscription authentication.
2002 - Subscriber id has been de-activated.
2003 - Subscriber id has been deleted.
3001 - The access or terminal number was not found.
3010 - The message recipient does not subscribe to the Sprint PCS Wireless Web Messaging Service on his or her phone.
3011 - The recipient's phone number is not for a Sprint PCS Phone.
3012 - The callback telephone number contains non-numeric characters.
3020 - The intended recipient has not subscribed to the Web Page Messaging feature.
4000 - The alias function has been deprecated.

DirectSMS  Xtra Errors Codes:

13000 - Not enough memory.
13001 - Network operation timed out.
13002 - Invalid reply from the server.
13003 - A background task is already taking place.
13004 - XML section was not found.
13005 - XML element was not found.
13006 - XML item was not found.
13007 - Aborted by user.
13008 - Feature is not available in the evaluation version.

TCP Errors:

10051: Network is unreachable.
10053: Software caused connection abort.
10054: Connection reset by peer.
10056: Socket is already connected.
10057: Socket is not connected.
10060: Connection timed out.
10061: No connection could be made because the target machine actively
refused it.
10065: Host is unreachable.
10091: Network subsystem is unavailable.
10210: Not enough memory.


11001: Host not found.

 

History

5.22.02 - Version 1.0 Released.

 

 

 



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 9/18/2004 8:36:01 AM.