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 : on SendSMS -- Step 1 - Create a new instance of DirectSMS Xtra and store it for a later use. Set SMS = new (Xtra "DirectSMS", "", "", 0) -- Step 2 - Send the SMS Set Error = smsSend (SMS, "+11005112396", "+11005112396", "This is the message", "From me") If (Error) then put "Error: " & Error exit end if -- Step 3 - Fequently call smsDone() to check the status of the SMS which is being -- sent in the background. repeat while not smsDone(SMS) end repeat Set Error = smsErrorCode(SMS) If (Error) then put "Error: " & Error exit end if -- Step 4 - Obtain information about the SMS Set TicketID = smsResult(SMS, 1) Set SMSPrice = smsResult(SMS, 2) -- Step 5 - Check the status of the SMS Set SMSStatus = 2 repeat while (SMSStatus = 1 or SMSStatus = 2 or SMSStatus = 3 or SMSStatus = 5) Set Error = smsStatus(SMS, TicketID) If (Error) then put "Error: " & Error exit end if repeat while not smsDone(SMS) end repeat Set Error = smsErrorCode(SMS) If (Error) then put "Error: " & Error exit end if Set SMSStatus = smsResult(SMS, 3) end repeat if SMSStatus = 0 or SMSStatus = 4 then put "The SMS was sent successfully. Server replied with: " & smsResult (SMS, 4) else put "Error: " & SMSStatus put "The SMS could not be sent. Server replied with: " & smsResult (SMS, 4) end if -- Step 6 - Delete the DirectSMS instance Set SMS = 0 end Sample Code for Authorware : -- Step 1 - Create a new instance of DirectSMS Xtra and store it for a later use. SMS:=NewObject("DirectSMS", "", "", 0) -- Step 2 - Send the SMS Error:=CallObject (SMS, "smsSend", "+11005112396", "+11005112396", "This is the message", "From me") if (Error) then Trace ("Error: " ^ String(Error)) exit end if -- Step 3 - Fequently call smsDone() to check the status of the SMS which is being -- sent in the background. repeat while (CallObject (SMS, "smsDone") = 0) end repeat Error:=CallObject (SMS, "smsErrorCode") if (Error) then Trace ("Error: " ^ String(Error)) exit end if -- Step 4 - Obtain information about the SMS TicketID:=CallObject(SMS, "smsResult", 1) SMSPrice:=CallObject(SMS, "smsResult", 2) -- Step 5 - Check the status of the SMS SMSStatus:=2 repeat while ((SMSStatus = 1)|(SMSStatus = 2)|(SMSStatus = 3)|(SMSStatus = 5)) Error:=CallObject(SMS, "smsStatus", TicketID) if (Error) then Trace ("Error: " ^ String(Error)) exit end if repeat while (CallObject (SMS, "smsDone") = 0) end repeat Error:=CallObject (SMS, "smsErrorCode") if (Error) then Trace ("Error: " ^ String(Error)) exit end if SMSStatus:=CallObject(SMS, "smsResult", 3) end repeat if ((SMSStatus=0)|(SMSStatus=4)) then Trace ("The SMS was sent successfully. Server replied with: " ^ CallObject(SMS, "smsResult", 4)) else Trace ("Error: " ^ String(SMSStatus)) Trace ("The SMS could not be sent. Server replied with: " ^ CallObject(SMS, "smsResult", 4)) end if -- Step 6 - Delete the DirectSMS instance DeleteObject(SMS)   JavaScript Sample Code for Director : function SendSMS() { // Step 1 - Create a new instance of DirectSMS Xtra and store it for a later use. var SMS = new xtra("DirectSMS", "", "", 0) //Step 2 - Send the SMS var Error = SMS.smsSend ("+11005112396", "+11005112396", "This is the message", "From me") if (Error) { trace( "Error: " + Error) abort() } // Step 3 - Fequently call smsDone() to check the status of the SMS which is being // sent in the background. while(!SMS.smsDone()) {} var Error = SMS.smsErrorCode() if (Error) { trace( "Error: " + Error) abort() } // Step 4 - Obtain information about the SMS var TicketID = SMS.smsResult(1) var SMSPrice = SMS.smsResult(2) // Step 5 - Check the status of the SMS var SMSStatus = 2 while (SMSStatus == 1 || SMSStatus == 2 || SMSStatus == 3 || SMSStatus == 5) { var Error = SMS.smsStatus(TicketID) if (Error) { trace( "Error: " + Error) abort() } while (!SMS.smsDone()) {} var Error = SMS.smsErrorCode() if (Error) { trace( "Error: " + Error) abort() } var SMSStatus = SMS.smsResult(3) } if (SMSStatus == 0 || SMSStatus == 4) { trace( "The SMS was sent successfully. Server replied with: " + SMS.smsResult (4))} else { trace ("Error: " + SMSStatus) trace( "The SMS could not be sent. Server replied with: " + SMS.smsResult (4)) } // Step 6 - Delete the DirectSMS instance SMS = 0 } 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.

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