Esendex Integration with Microsoft Exchange Server

Esendex Integration with Microsoft Exchange Server

Esendex Integration Using COM

Esendex Integration Using COM

Targeted at Microsoft Visual C++ 7 and Microsoft Visual Basic 6

Introduction

This document describes how to use the Esendex SMS service with Microsoft Visual C++ 7 and Microsoft Visual Basic 6. To aid with the integration, Esendex provides a lightweight COM component that can be freely distributed with your application.

The following information is available:

  • Installation
  • Using the component in your code
  • Object model

Installation

To use the COM component, you must register it with the system. To do this, type the following from a command prompt:

REGSVR32 EsendexSdk2.DLL

You will see a message that the component has been successfully registered.

Using the component in Visual C++ 6

The easiest way to use the component in Visual C++ is to import it, as follows:

#import "EsendexSdk2.dll"

Note that you may need to specify a path to the location where you installed the component.

You can then send a message as follows:

EsendexLib::SendService2 spSendService;

spSendService.CreateInstance(uuidof(EsendexLib::SendService2));

spSendService->Initialise("MyUserName", "MyPassword", "MyAccount");

spSendService->SendMessage("441234567890", "Hello”, EsendexLib::MESSAGE_TYPE_TEXT);

MFC users should remember to call AfxOleInit() in the application’s InitInstance() method, whilst non-MFC users should initialize COM with a call to CoInitialize().

Send Message sample

The SendMessage folder contains a simple console application (SendMessage.sln) that demonstrates how to send an SMS message.

Application flow is as follows:

  • SendMessage.cpp contains a line to import the Esendex type library.
  • Constants are defined for the username, password, account and recipient. You will need to change these to contain your own details.
  • The main method Intialises the COM subsystem.
  • The SendWorker() method is called to Send the SMS message.
  • The Esendex SendService2 component is created.
  • The user’s account information is passed to the SendService2 component.
  • The SendMessage method is used to despatch the SMS message.

Messenger Sample

The Messenger folder contains an MFC dialog application (EsendexMessenger.sln) that displays the contents of your Esendex inbox. You can delete messages from your inbox and send an SMS message.

Application flow is as follows:

  • stdafx.h contains a line to import the Esendex type library.
  • CEsendexMessengerApp::InitInstance() is called by MFC to initialise the application.
  • AfxOleInit() to the application’s InitInstance() method. This initialises the COM subsystem.
  • A CLoginDialog is instantiated and displayed to enable the user to enter account information. The details are stored in CInboxApp ready for calls to the Esendex service.
  • A CLoginDialog is instantiated and displayed to show the contents of the user’s inbox.
  • MFC calls CInboxDlg::OnInitDialog to show the dialog box.
  • InitialiseInboxService() is called to create the Esendex Inbox component.
  • PopulateList() is called to add the contents of the user’s inbox to the list view control. At this point, the account information entered by the user is used in the GetMessages method call. If the account information is incorrect, and error message is displayed. The user should then use the Account button to re-enter their information.
  • The OnAccount(), OnSend(), OnSendFull(), OnDelete(), and OnRefresh() methods are called by MFC in response to the user clicking relevant buttons on the dialog box.

Using the component in Visual Basic 6

To use the component in Visual Basic, do the following:

  1. From the Project menu, choose References.
  2. In the Available References list, select “Esendex 2.0 Type Library”.
  3. Click OK.

You can then send a message as follows:

Dim service as new EsendexLib.SendService2

service.Initialise "MyUserName", "MyPassword", "MyAccount"

service.SendMessage "441234567890", "Hello”, EsendexLib.MESSAGE_TYPE_TEXT);

The following code samples are available:

  • Send Message – A simple application that sends an SMS message.
  • Inbox – A more complex application that displays the contents of your Esendex inbox and enables you to delete items from it, as well as sending SMS messages.

Object model

This section describes the complete Esendex object model:

ISendService2 interface

Contains functions and methods that enable you to send SMS messages.

Implemented by

SendService2 class

Visual Basic sample code

Dim service as new EsendexLib.SendService2

C++ sample code

EsendexLib::SendService2 spSendService;

spSendService.CreateInstance(uuidof(EsendexLib::SendService2));

Initialise method

Initialise the class with your Esendex credentials. You must call this method before you call any other on the interface.

Visual Basic syntax

Sub Initialise(Username As String, Password As String, Account As String, [IsServerSide])

C++ syntax

Initialise(_bstr_t Username, _bstr_t Password, _bstr_t Account, _variant_t IsServerSide);

Parameters

Username

Your Esendex username.

Password

Your Esendex password.

Account

Your Esendex account number.

IsServerSide (optional)

True if the component is running within an ASP page; false or otherwise. The default is false.

SendMessage function

Sends an SMS message to the specified recipient using the default originator and validity period.

Visual Basic syntax

Function SendMessage(Recipient As String, Body As String, Type As MESSAGE_TYPE) As String

C++ syntax

_bstr_t SendMessage(_bstr_t Recipient, _bstr_t Body, MESSAGE_TYPE Type);

Parameters

Recipient

The mobile number to which the message will be sent.

Body

The content of the message. The maximum length depends on the value you specify for Type. It can be up to 160 characters for Text, 140 characters for Binary and SmartMessaging or 70 characters for Unicode.

Type

The type of message contained in Body. This can be Text, Binary, SmartMessage or Unicode.

Return value

The ID of the message assigned by Esendex.

SendMessageFull function

Sends an SMS message to the specified recipient.

Visual Basic syntax

Function SendMessageFull(Originator As String, Recipient As String, Body As String, Type As MESSAGE_TYPE, ValidityPeriod As Long) As String

C++ syntax

_bstr_t SendMessageFull(_bstr_t Originator, _bstr_t Recipient, _bstr_t Body, MESSAGE_TYPE Type, long ValidityPeriod);

Parameters

Originator

The alias the message should appear to come from. This can be another mobile number or up to 11 alpha-numeric characters. With Evaluation accounts, this parameter must be set to the virtual mobile number assigned by Esendex. With Premium Rate accounts, this parameter must be set to the account short code.

Recipient

The mobile number to which the message will be sent.

Body

The content of the message. The maximum length depends on the value you specify for Type. It can be up to 160 characters for Text, 140 characters for Binary and SmartMessaging or 70 characters for Unicode.

Type

The type of message contained in Body. This can be Text, Binary, SmartMessage or Unicode.

ValidityPeriod

The time, in hours, for which the message is valid. You can specify zero to use the default validity period.

Return value

The ID of the message assigned by Esendex.

SendMessageMultipleRecipients function

Sends an SMS message to the specified recipients using the default originator and validity period.

Visual Basic syntax

Function SendMessageMultipleRecipients (Recipients As String, Body As String, Type As MESSAGE_TYPE) As StringCollection2

C++ syntax

IStringCollection2Ptr SendMessageMultipleRecipients (_variant_t Recipients, _bstr_t Body, MESSAGE_TYPE Type);

Parameters

Recipients

A comma-separated list of mobile numbers to which the message will be sent.

Body

The content of the message. The maximum length depends on the value you specify for Type. It can be up to 160 characters for Text, 140 characters for Binary and SmartMessaging or 70 characters for Unicode.

Type

The type of message contained in Body. This can be Text, Binary, SmartMessage or Unicode.

ValidityPeriod

The time, in hours, for which the message is valid. You can specify zero to use the default validity period.

Return value

An IStringCollectionPtr containing the IDs of the messages assigned by Esendex.

SendMessageMultipleRecipientsFull function

Sends an SMS message to the specified recipient.

Visual Basic syntax

Function SendMessageMultipleRecipientsFull (Originator As String, Recipients As String, Body As String, Type As MESSAGE_TYPE, ValidityPeriod As Long) As StringCollection2

C++ syntax

IStringCollection2Ptr SendMessageMultipleRecipientsFull (_bstr_t Originator, _variant_t Recipients, _bstr_t Body, MESSAGE_TYPE Type, long ValidityPeriod);

Parameters

Originator

The alias the message should appear to come from. This can be another mobile number or up to 11 alpha-numeric characters. With Evaluation accounts, this parameter must be set to the virtual mobile number assigned by Esendex. With Premium Rate accounts, this parameter must be set to the account short code.

Recipients

A comma-separated list of mobile numbers to which the message will be sent.

Body

The content of the message. The maximum length depends on the value you specify for Type. It can be up to 160 characters for Text, 140 characters for Binary and SmartMessaging or 70 characters for Unicode.

ValidityPeriod

The time, in hours, for which the message is valid. You can specify zero to use the default validity period.

Return value

An collection containing the IDs of the messages assigned by Esendex.

GetMessageStatus function

Returns the status of a previously submitted message.

Visual Basic syntax

Function GetMessageStatus(MessageID as String) As MESSAGE_STATUS

C++ syntax

MESSAGE_STATUS GetMessageStatus(_bstr_t MessageID);

Parameters

Message

The ID of the message whose status you want to query.

Return value

The message status. This can be Queued, Sent, Delivered or Failed.

IInboxService2 interface

Contains functions and methods that enable you to work with your Esendex inbox.

Implemented by

Inbox2 class

Visual Basic sample code

Dim service as new EsendexLib.InboxService2

C++ sample code

EsendexLib::SendService2 spInboxService;

spInboxService.CreateInstance(uuidof(EsendexLib::InboxService2));

Initialise method

Initialise the class with your Esendex credentials. You must call this method before you call any other on the interface.

Visual Basic syntax

Sub Initialise(Username As String, Password As String, Account As String, [IsServerSide])

C++ syntax

Initialise(_bstr_t Username, _bstr_t Password, _bstr_t Account, _variant_t IsServerSide);

Parameters

Username

Your Esendex username.

Password

Your Esendex password.

Account

Your Esendex account number.

IsServerSide (optional)

True if the component is running within an ASP page; false or otherwise. The default is false.

DeleteMessage method

Deletes a message from your Esendex inbox.

Visual Basic syntax

Sub DeleteMessage(MessageID as String)

C++ syntax

DeleteMessage(_bstr_t MessageID);

Parameters

Message

The ID of the message you want to delete.

DeleteMessages method

Deletes multiple messages from your Esendex inbox.

Visual Basic syntax

Sub DeleteMessages(MessageIDs as String)

C++ syntax

DeleteMessage(_bstr_t MessageIDs);

Parameters

Messages

A comma-separated list containing the IDs of the messages you want to delete.

GetMessages function

Retrieves messages from your Esendex inbox.

Visual Basic syntax

Function GetMessages() As ObjectCollection

C++ syntax

IObjectCollectionPtr GetMessages();

Return value

A collection of messages contained in your Esendex inbox.

GetMessageByID function

Retrieves a message from your Esendex inbox.

Visual Basic syntax

Function GetMessageByID(MessageID as String) As SMSMessage2

C++ syntax

ISMSMessage2Ptr GetMessageByID(_bstr_t MessageID);

Parameters

MessageID

The ID of the message you want to retrieve.

Return value

A message from your Esendex inbox.

GetMessagesForDay function

Retrieves messages from your Esendex inbox for a given day.

Visual Basic syntax

Function GetMessagesForDay(Year as Long, Month as Long, Day as Long) As ObjectCollection

C++ syntax

IObjectCollectionPtr GetMessages(long Year, long Month, long Day);

Parameters

Year, Month, Day

The year, month and day of the messages to retrieve.

Return value

A collection of messages contained in your Esendex inbox.

GetMessagesForDateRange function

Retrieves messages from your Esendex inbox for a given date range.

Visual Basic syntax

Function GetMessagesForDateRange(StartDate as Date, EndDate as Date) As ObjectCollection

C++ syntax

IObjectCollectionPtr GetMessages(Date StartDate, Date EndDate);

Parameters

StartDate

The inclusive date of the earliest message to retrieve.

EndDate

The inclusive date of the latest message to retrieve.

Return value

A collection of messages contained in your Esendex inbox.

GetMessagesByID function

Retrieves messages from your Esendex inbox.

Visual Basic syntax

Function GetMessagesByID(MessageIDs as String) As ObjectCollection

C++ syntax

IObjectCollectionPtr GetMessagesByID(_bstr_t MessageIDs);

Parameters

MessageIDs

A comma-separated list containing the IDs of the messages you want to retrieve.

Return value

A collection of messages contained in your Esendex inbox.

AccountService interface

Enables you to find out information about your account.

Implemented by

AccountService class

Visual Basic sample code

Dim service as new EsendexLib.AccountService

C++ sample code

EsendexLib::AccountService spAccountService;

spAccountService.CreateInstance(uuidof(EsendexLib::AccountService));

Initialise method

Initialise the class with your Esendex credentials. You must call this method before you call any other on the interface.

Visual Basic syntax

Sub Initialise(Username As String, Password As String, Account As String, [IsServerSide])

C++ syntax

Initialise(_bstr_t Username, _bstr_t Password, _bstr_t Account, _variant_t IsServerSide);

Parameters

Username

Your Esendex username.

Password

Your Esendex password.

Account

Your Esendex account number.

IsServerSide (optional)

True if the component is running within an ASP page; false or otherwise. The default is false.

GetMessageLimit function

Returns the remaining message limit on your account.

Visual Basic syntax

Function GetMessageLimit() As Long

C++ syntax

long GetMessageLimit();

Return value

The number of messages remaining on your account.

GetAccountFeatures function

Returns the features that are enabled on your account.

Visual Basic syntax

Function GetAccountFeatures() As Long

C++ syntax

long GetAccountFeatures();

Return value

The features enabled on your account. This can be a combination of: ACCOUNT_FEATURE_NONE, ACCOUNT_FEATURE_SERVICE_ALIASING and ACCOUNT_FEATURE_INBOX.

GetAccountState function

Returns a state object that contains information about your account.

Visual Basic syntax

Function GetAccountState() As AccountState

C++ syntax

IAccountStatePtr GetAccountState();

Return value

An object that contains information about your account, including the ID assigned by Esendex, the reference, address, service alias, messsage limit and features.

ContactService interface

Enables you to retrieve, add, edit and delete contacts and contact groups.

Implemented by

ContactService class

Visual Basic sample code

Dim service as new EsendexLib.ContactService

C++ sample code

EsendexLib::ContactService spContactService;

spContactService.CreateInstance(uuidof(EsendexLib::ContactService));

Initialise method

Initialise the class with your Esendex credentials. You must call this method before you call any other on the interface.

Visual Basic syntax

Sub Initialise(Username As String, Password As String, Account As String, [IsServerSide])

C++ syntax

Initialise(_bstr_t Username, _bstr_t Password, _bstr_t Account, _variant_t IsServerSide);

Parameters

Username

Your Esendex username.

Password

Your Esendex password.

Account

Your Esendex account number.

IsServerSide (optional)

True if the component is running within an ASP page; false or otherwise. The default is false.

GetContacts function

Returns a list of contacts associated with your account.

Visual Basic syntax

Function GetContacts() As ObjectCollection

C++ syntax

IObjectCollectionPtr GetContacts();

Return value

A collection containing the contacts associated with your account.

GetGroups function

Returns a list of groups associated with your account.

Visual Basic syntax

Function GetGroups() As ObjectCollection

C++ syntax

IObjectCollectionPtr GetGroups ();

Return value

A collection containing the groups associated with your account.

AddContact function

Adds a contact to your account.

Visual Basic syntax

Function AddContact(Contact) As String

C++ syntax

_bstr_t AddContact(IContactPtr Contact);

Parameters

Contact

The contact you want to add.

Return value

The ID assigned to the contact by Esendex.

AddContacts function

Adds multiple contacts to your account.

Visual Basic syntax

Function AddContacts(Contacts as ObjectCollection) As StringCollection2

C++ syntax

IStringCollection2Ptr AddContact(IObjectCollectionPtr Contacts);

Parameters

Contacts

A collection containing the contacts you want to add.

Return value

A collection containing the IDs assigned to the contacts by Esendex.

AddGroup function

Adds a group to your account.

Visual Basic syntax

Function AddGroup(Group, MemberIDs as String) As String

C++ syntax

_bstr_t AddGroup(IGroupPtr Group, _bstr_t MemberIDs);

Parameters

Group

The group you want to add.

MemberIDs

A comma-separated list containing the IDs of the contacts that should become members of the group.

Return value

The ID assigned to the group by Esendex.

DeleteContact method

Deletes a contact from your account.

Visual Basic syntax

Sub DeleteContact(ContactID as String)

C++ syntax

void DeleteContact(_bstr_t ContactID);

Parameters

ContactID

The ID of the contact you want to delete.

DeleteContacts method

Deletes multiple contacts from your account.

Visual Basic syntax

Sub DeleteContacts(ContactIDs as String)

C++ syntax

void DeleteContacts(_bstr_t ContactIDs);

Parameters

ContactIDs

A comma-separated list containing the IDs of the contacts you want to delete.

DeleteGroup method

Deletes a group from your account.

Visual Basic syntax

Sub DeleteGroup(GroupID as String, [IncludeMembers])

C++ syntax

void DeleteContact(_bstr_t GroupID, _variant_t IncludeMembers);

Parameters

GrouptID

The ID of the group you want to delete.

IncludeMembers (optional)

True if you want to delete the contact members as well as the group.

UpdateContact method

Updates one of your account’s contacts.

Visual Basic syntax

Sub UpdateContact(Contact)

C++ syntax

void UpdateContact(IContactPtr Contact);

Parameters

Contact

The contact you want to update.

UpdateGroup method

Updates one of your account’s groups.

Visual Basic syntax

Sub UpdateGroup(Group, MemberIDs as String)

C++ syntax

void UpdateGroup(IGroupPtr Group, _bstr_t MemberIDs);

Parameters

Group

The group you want to update.

MemberIDs

A comma-separated list containing the IDs of the contacts that should become members of the group.

GetContact function

Retrieves a contact from your account.

Visual Basic syntax

Function GetContact(ContactID as String) As Contact

C++ syntax

IContactPtr GetContact(_bstr_t ContactID);

Parameters

ContactID

The ID of contact you want to retrieve.

Return value

The Contact.

GetGroup function

Retrieves a group from your account.

Visual Basic syntax

Function GetGroup(GroupID as String) As Group

C++ syntax

IGroupPtr GetGroup (_bstr_t GroupID);

Parameters

GroupID

The ID of the group you want to retrieve.

Return value

Top View