8. API (SMS Messaging Server Application Programming Interface)
 
[API topics: 8.1 Introduction - 8.2 Classes - 8.3 MessageDB class - 8.4 Message class - 8.5 Constants class - Advanced Administration classes]

 

8.3. MessageDB Class


Properties

 Property  Type  Description
 Last Error  Number  Completion code of the last called function.


Functions

 Function  Description
 Open  Open the Message Database.
 Close  Close the Message Database.
 Count  Count messages in the Message Database.
 Create  Create a new message in the Message Database.
 Delete  Delete a message.
 Load  Load a message.
 FindFirstMessage  Return the first message that matches the condition.
 FindNextMessage  Return the next message that matches the condition.
 GetDirectionDescription  Look-up the friendly description of the given description code.
 GetTypeDescription  Look-up the friendly description of the given type-code.
 GetStatusDescription  Look-up the friendly description of the given status-code.
 GetBodyFormatDescription  Look-up the friendly format description of the given body format code.




8.3.1. MessageDB - Properties


LastError property

Result the last called function. To find the error description of a given error code, go to the online error codes page.

Example: 
   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database

   ...
 [Top]



8.3.2. MessageDB - Functions


Open function

Open the Message Database. You must open the message database before you can perform any operation on the Message Database,
like counting records, creating new records, deleting records, etc.
When you're finished accessing the database, you must call Close in order to close the database.

Parameters: 
   None.
Return value: 
   Always 0. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   ...

   objMessageDB.Close                                         ' Close the Database
   WScript.Echo "Closed."
[Top]



Close function

Close the Message Database. You must call this function to close the Message Database that was open by the Open call.
You can even call this function if a preceding Open was not completed successfully (the function will then simply be ignored).

Parameters: 
   None.
Return value: 
   Always 0. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   ...

   objMessageDB.Close                                         ' Close the Database
   WScript.Echo "Closed."
[Top]



Count function

Count the number of messages in the Message Database. You can apply a filter. When an empty string is passed as filter, all messages are filtered.
For more information about filters, click here.

Parameters: 
   Filter (String) - A message filter. Pass an empty string to filter all messages.
Return value: 
   Always 0. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB, objConstants, numRecords
   Dim strFilter

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   ' Count all messages in the database with direction Outgoing and status Success 
   strFilter = "Direction=" & objConstants.MESSAGEDIRECTION_IN & " AND " & _
               "Status=" & objConstants.MESSAGESTATUS_SUCCESS
   numRecords = objMessageDB.Count( strFilter )               ' Count the records
   WScript.Echo "Count, result: " &  objMessageDB.LastError   
   If( objMessageDB.LastError <> 0 ) Then
      objMessageDB.Close
      WScript.Quit
   End If

   WScript.Echo "Number of messages: " &  numRecords  

   objMessageDB.Close                                         ' Close the Database
   WScript.Echo "Closed."
[Top]



Create function

Create a new message in the Message Database.

Parameters: 
   None.
Return value: 
   A new Message object. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB, objMessage, objConstants

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   Set objMessage   = objMessageDB.Create
   WScript.Echo "Create, result: " & objMessageDB.LastError
   If( objMessageDB.LastError <> 0 ) Then
      objMessageDB.Close
      WScript.Quit
   End If  

   WScript.Echo "Message successfully created, recordID: " & objMessage.ID

   objMessage.Direction    = objConstants.MESSAGEDIRECTION_OUT
   objMessage.Type         = objConstants.MESSAGETYPE_SMS
   objMessage.Status       = objConstants.MESSAGESTATUS_PENDING
   objMessage.ToAddress    = "+31624896641"
   objMessage.Body         = "Test message"

   objMessageDB.Save( objMessage )
   WScript.Echo "Save, result " & objMessageDB.LastError

   objMessageDB.Close
   WScript.Echo "Closed."
[Top]



Delete function

Delete a message from the Message Database. You can apply a filter. When an empty string is passed as filter, all messages are deleted.
For more information about filters, click here.

Parameters: 
   Filter (String) - A message filter. Pass an empty string to filter all messages.
Return value: 
   Always 0. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB, objConstants

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   objMessageDB.Delete( "ID > 46 And ID < 49" )               ' Delete Message with ID=47 or ID=48
   WScript.Echo "Delete, result: " & objMessageDB.LastError

   objMessageDB.Close                                         ' Close the Database
   WScript.Echo "Closed."
[Top]



Load function

Load a message from the Message Database.

Parameters: 
   Message ID (Number) - Record ID of the message in the Messages database
   Reserved (Boolean)  - This parameter is not used
Return value: 
   A new Message object. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB, objMessage, objConstants

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   Set objMessage   = objMessageDB.Load( 5 )                  ' Load Message with Message ID 5
   WScript.Echo "Load, result: " & objMessageDB.LastError
   If( objMessageDB.LastError <> 0 ) Then
      objMessageDB.Close
      WScript.Quit
   End If  

   WScript.Echo "Message successfully loaded, ID: " & objMessage.ID

   objMessageDB.Close
   WScript.Echo "Closed."
[Top]



FindFirstMessage / FindNextMessage functions

Find messages in the Message Database. You can apply a filter to filter messages. When an empty string is passed as filter, all messages are selected.
For more information about filters, click here.

Parameters FindFirstMessage: 
   Filter (String)          - A message filter. Pass an empty string to filter all messages.
   Order (String, Optional) - Indicates how the results are sorted. 
                              Examples: "Sender", "Sender ASC", "Recipient DESC", "ID ASC, Sender DESC"
   Top (Number, Optional)   - Set a limit to the number of records in the result.
   Reserved (Boolean)       - This parameter is not used
Parameters FindNextMessage: 
   None.
Return value: 
   A new Message object. Check LastError property to see if the function was completed successfully.
Example: 
   Option Explicit

   Dim objMessageDB, objMessage, objConstants

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   ' Find all messages
   Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message that matches the qualification
   While( objMessageDB.LastError = 0 ) 
      WScript.Echo "Message found: " & objMessage.ID
      WScript.Echo "  Sender: "    & objMessage.FromAddress
      WScript.Echo "  Recipient: " & objMessage.ToAddress
      Set objMessage   = objMessageDB.FindNextMessage()       ' Find next message that matches the qualification
   WEnd  

   ' Find all outgoing messages sorted on Status (Ascending)
   WScript.Echo vbCrLf
   Set objMessage   = objMessageDB.FindFirstMessage( "Direction = " & objConstants.MESSAGEDIRECTION_OUT, "Status ASC" )                                                               
   While( objMessageDB.LastError = 0 ) 
      WScript.Echo "Message found: " & objMessage.ID
      WScript.Echo "  Sender: "    & objMessage.FromAddress
      WScript.Echo "  Recipient: " & objMessage.ToAddress
      Set objMessage   = objMessageDB.FindNextMessage()  
   WEnd  

   objMessageDB.Close
   WScript.Echo "Closed."
[Top]


 
GetDirectionDescription,
GetTypeDescription,
GetStatusDescription,
GetBodyFormatDescription functions

GetDirectionDescription returns the friendly description of the given Direction.
GetTypeDescription returns the friendly description of the given Type.
GetStatusDescription returns the friendly description of the given Status.
GetBodyFormatDescription returns the friendly description of the given BodyFormat.

Parameters: 
   A numeric code.
Return value: 
    The description string.
Example: 
   Option Explicit

   Dim objMessageDB, objMessage, objConstants

   Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
   Set objConstants = CreateObject( "AxMmServer.Constants" ) 

   objMessageDB.Open 
   WScript.Echo "Open, result: " &  objMessageDB.LastError    ' Open the Database
   If( objMessageDB.LastError <> 0 ) Then
      WScript.Quit
   End If

   ' Find first message
   Set objMessage   = objMessageDB.FindFirstMessage( "" )     ' Find first message that matches the qualification
   If( objMessageDB.LastError = 0 ) Then
      WScript.Echo "Messgage ID: " & objMessage.ID
      WScript.Echo "Direction: " & objMessage.Direction
      WScript.Echo "Direction string: " & objMessageDB.GetDirectionDescription( objMessage.Direction )
      WScript.Echo "Type: " & objMessage.Type
      WScript.Echo "Type string: " & objMessageDB.GetTypeDescription( objMessage.Type )
      WScript.Echo "Status: " & objMessage.Status
      WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.Status )
      WScript.Echo "BodyFormat: " & objMessage.BodyFormat
      WScript.Echo "BodyFormat string: " & objMessageDB.GetBodyFormatDescription( objMessage.BodyFormat )
   End If  
 
   objMessageDB.Close
   WScript.Echo "Closed."
[Top]




8.3.3. Filters


A filter can be used to filter messages from the message database. There are three functions having a filter as an optional parameter:
You can use a SQL-formatted 'where' condition, and use database fields and constants as operands in the clause.


Examples: 
Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

objMessageDB.Count( Status = objConstants.MESSAGESTATUS_SUCCESS )
objMessageDB.Count( ID > 1 AND ID < 100 AND ChannelID = 1001 AND Body LIKE '%request%' )
objMessageDB.Delete( Sender = '+31625044454' AND Direction = objConstants.MESSAGEDIRECTION_IN )