/client

SMSCclientSEMA

Overview

Class SMSCclientSEMA
Namespace smscc.SEMA
Parent TComponent
Interfaces ISMSCclientSEMA

Methods

tcpConnect Connect to the SMSC on network protocol (TCP/IP) level.
tcpDisconnect Disconnect from the SMSC on network protocol (TCP/IP) level.
semaInitializeSession Login and initialize communication session on SMPP protocol level.
semaSubmitMessage Submit message to the SMSC.
semaSubmitMessageAsync Submit message in asynchronous mode.

Events

OnTcpDisconnected Event triggered on disconnection on network protocol (TCP/IP) level.
OnSemaMessageReceived Event triggered on message being received from the SMSC.
OnSemaMessageCompleted Event triggered on multipart message is reconstructed.
OnSemaSubmitResponseAsyncReceived Event triggered on receive of message submission confirmation in asynchronous submit mode.
OnSemaStatusReportReceived Event triggered on receive of status report.

Properties

Connected Returns information on connection state.
KeepAliveInterval Connection keep-alive timing.
ResponseTimeOut Communication timeout.
ImmediateResponse Status report confirmation mode.

Methods

tcpConnect

Connect to the SMSC on network protocol (TCP/IP) level.

int tcpConnect(string RemoteHost, int RemotePort);

Parameters

RemoteHost
Either numeric or alphanumeric TCP/IP address of the SMSC ("192.168.8.16", "smsc.telecom.com" etc.)
RemotePort
Port number of the SMSC for the TCP/IP protocol connection.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

tcpDisconnect

tcpDisconnect

Disconnect from the SMSC on network protocol (TCP/IP) level.

void tcpDisconnect();

See Also

tcpConnect

semaInitializeSession

Login and initialize communication session on SMPP protocol level.

int semaInitializeSession(string Originator, int TON, int NPI);

Parameters

Originator
SMSC account identifier.
TON
Type Of Number.
NPI
Numbering Plan Identifier.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code Positive value means SEMA protocol Operation Result.

semaSubmitMessage

Submit message to the SMSC.

int semaSubmitMessage(string Destination, string Originator, int OTON, int ONPI, string Content, EncodingEnum Encoding, string UserDataHeader, SubmitOption Options, ref List< string > MessageIDs, ref List< DateTime > TimeStamps);

Parameters

Destination
Message recipient identifier. Usually this is mobile phone number in fully qualified format.
Originator
Message sender identifier. Usually this is is number of the SMSC's account (a short GSM number). This parameter can also be an alphanumeric string or general phone number where permitted.
OTON
Type Of Number (TON) for Originator parameter.
ONPI
Numbering Plan Identifier (NPI) for Originator parameter.
Content
The text or content of the message to be sent. The conversion of the characters transferred by parameter to the mobile infrastructure alphabet is done according to the value passed via Encoding parameter.
Encoding
Decides on the which conversion is applied to the Content parameter to convert it to the character set supported by message. Accepted values, members of EncodingEnum type:
et7BitText Message is encoded using 7-bit GSM alphabet as in [03.38] (6.2).
et8BitHexadecimal Message contains binary data encoded in hexadecimal format. Each two hexadecimal digits encode one byte of data.
etUCS2Text Message contains Unicode character string encoded according to UCS2 coding.
etISO88591 Message encoded as Latin 1 (ISO-8859-1). Support for this encoding may depend on SMSC configuration.
etISO88595 Message encoded as Cyrllic (ISO-8859-5). Support for this encoding may depend on SMSC configuration.
etISO88598 Message encoded as Latin/Hebrew (ISO-8859-8). Support for this encoding may depend on SMSC configuration.
etWAPPushOrMMS WAP Push/MMS required encoding. Sets F5 (hex) as the Data Coding Scheme (DCS) value. Required by some SMSC providers.
UserDataHeader
User Data Header (UDH) for the message. The header must be passed as a byte string in hexadecimal format. For example: "06050415831583" is 7 bytes large header.
Options
Options that can be set for message submitted as per SubmitOptionEnum type definition. It is possible to set more than one option by using the binary OR operator on the chosen option values. Accepted values:
soRequestStatusReport Request status report for the message.
soDirectDisplay Message will be sent as a Direct Display (FlashSMS) type message.
soDeliveryTimeRelative DeliveryTime is considered relative.
soDeliveryTimeAbsolute DeliveryTime is considered absolute.
soValidityPeriodRelative Validity period will be considered relative.
soValidityPeriodAbsolute Validity period will be considered absolute.
soMessageClass0 Message class will be set to 0.
soMessageClass1 Message class will be set to 1.
soMessageClass2 Message class will be set to 2.
soMessageClass3 Message class will be set to 3.
soZeroSMS Message will be delivered as "ZERO" SMS.
MessageIDs
Message identifier returned by SMSC. Allows to identify status report returned via OnSemaStatusReportReceived event for the message. The value is returned by reference during the function call which means that a reference to variable has to be passed.
TimeStamps
Time of reception of the message to transfer by the SMSC. Used to identify status report returned by the SMSC.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means SEMA protocol Operation Result.

Remarks

Function returns after receiving from SMSC a response to the submission operation. If the status report (soRequestStatusReport) request option is set in the Options parameter a status report will be returned by the OnSemaStatusReportReceived event.

See Also

semaSubmitMessageAsync

semaSubmitMessageAsync

Submit message in asynchronous mode.

int semaSubmitMessageAsync(string Destination, string Originator, int OTON, int ONPI, string Content, EncodingEnum Encoding, string UserDataHeader, SubmitOption Options, ref List< uint > OperationReferences);

Parameters

Destination
Message recipient identifier. Usually this is mobile phone number in fully qualified format.
Originator
Message sender identifier. Usually this is is number of the SMSC's account (a short GSM number). This parameter can also be an alphanumeric string or general phone number where permitted.
OTON
Type Of Number (TON) for Originator parameter.
ONPI
Numbering Plan Identifier (NPI) for Originator parameter.
Content
The text or content of the message to be sent. The conversion of the characters transferred by parameter to the mobile infrastructure alphabet is done according to the value passed via Encoding parameter.
Encoding
Decides on the which conversion is applied to the Content parameter to convert it to the character set supported by message. Accepted values, members of EncodingEnum type:
et7BitText Message is encoded using 7-bit GSM alphabet as in [03.38] (6.2).
et8BitHexadecimal Message contains binary data encoded in hexadecimal format. Each two hexadecimal digits encode one byte of data.
etUCS2Text Message contains Unicode character string encoded according to UCS2 coding.
etISO88591 Message encoded as Latin 1 (ISO-8859-1). Support for this encoding may depend on SMSC configuration.
etISO88595 Message encoded as Cyrllic (ISO-8859-5). Support for this encoding may depend on SMSC configuration.
etISO88598 Message encoded as Latin/Hebrew (ISO-8859-8). Support for this encoding may depend on SMSC configuration.
etWAPPushOrMMS WAP Push/MMS required encoding. Sets F5 (hex) as the Data Coding Scheme (DCS) value. Required by some SMSC providers.
UserDataHeader
User Data Header (UDH) for the message. The header must be passed as a byte string in hexadecimal format. For example: "06050415831583" is 7 bytes large header.
Options
Options that can be set for message submitted as per SubmitOptionEnum type definition. It is possible to set more than one option by using the binary OR operator on the chosen option values. Accepted values:
soRequestStatusReport Request status report for the message.
soDirectDisplay Message will be sent as a Direct Display (FlashSMS) type message.
soDeliveryTimeRelative DeliveryTime is considered relative.
soDeliveryTimeAbsolute DeliveryTime is considered absolute.
soValidityPeriodRelative Validity period will be considered relative.
soValidityPeriodAbsolute Validity period will be considered absolute.
soMessageClass0 Message class will be set to 0.
soMessageClass1 Message class will be set to 1.
soMessageClass2 Message class will be set to 2.
soMessageClass3 Message class will be set to 3.
soZeroSMS Message will be delivered as "ZERO" SMS.
OperationReferences
Identifier of the transaction with the SMSC. Allows matching the submission with return code provided by the semaSubmitResponseAsyncReceivedEvent event.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means SEMA protocol Operation Result.

Remarks

Function returns immediately after submitting the message to the SMSC. TimeStamp required to match appropriate Stetus Report is returned via semaSubmitResponseAsyncReceivedEvent event.

See Also

semaSubmitMessage

Events

OnTcpDisconnected

Event triggered on disconnection on network protocol (TCP/IP) level.

public delegate void tcpDisconnectedEvent(Object Sender, tcpDisconnectedEventArgs e);

Description

The event informs about the tear down of connection between the library and the SMSC on the network layer level (TCP). Such situation may be due to disconnection by SMSC (as per the rules of protocol after the timeout of inactivity of the component, in the case when connection is not kept alive) and in the case of disconnection for other reasons concerning functioning of the network layer.

Parameters

Sender

Object sending the event.

e

Object encapsulating event parameters.

int Reason
When the result is zero the connection has been disconnected by remote party. When the result is -1 then connection has been ended by the component itself, because inproperly formatted response has been received during the attempt to communicate with the remote party. Positive value means Network Error Code.

See Also

SMSCclientSEMA.tcpDisconnect, tcpDisconnectedEvent, tcpDisconnectedEventArgs

OnSemaMessageReceived

Event triggered on message being received from the SMSC.

public delegate void semaMessageReceivedEvent(Object Sender, semaMessageReceivedEventArgs e);

Description

This event will occur both in the situation of receiving messages previously stored in the SMSC's queues as well as messages received while the component is connected to the SMSC.

Parameters

Sender

Object sending the event.

e

Object encapsulating event parameters.

string Destination
Usually this is mobile phone number in canonical format.
int DTON
Value denoting Type Of Number.
int DNPI
Value denoting Numbering Plan Identifier.
string Originator
Usually this is is number of the SMSC's account (a short GSM number). This parameter can also be an alphanumeric string or phone number.
int OTON
Value denoting Type Of Number.
int ONPI
Value denoting Numbering Plan Identifier.
String Content
This can be ASCII characters string or hexadecimally encoded binary content. This value should be considered according to the value of Encoding property.
EncodingEnum Encoding
Possible values as per EncodingEnum type definition.
string UserDataHeader
If the message received contains the User Data Header (UDH), it will be returned in this field as hexadecimally encoded binary content, for example: "06050415831583". If the message does not have UDH empty string is returned.
string TimeStamp
Date and time according to the SMSC configuration standard.

See Also

semaMessageReceivedEvent, semaMessageReceivedEventArgs

OnSemaMessageCompleted

Event triggered on multipart message is reconstructed.

public delegate void semaMessageCompletedEvent(Object Sender, semaMessageCompletedEventArgs e);

Description

The event informs that the client has received a message which either completes a multipart message or does not need completition.

Parameters

Sender

Object sending the event.

e

Object encapsulating event parameters.

string Destination
Usually this is mobile phone number in canonical format.
int DTON
Value denoting Type Of Number.
int DNPI
Value denoting Numbering Plan Identifier.
string Originator
Usually this is is number of the SMSC's account (a short GSM number). This parameter can also be an alphanumeric string or phone number.
int OTON
Value denoting Type Of Number.
int ONPI
Value denoting Numbering Plan Identifier.
String Content
This can be ASCII characters string or hexadecimally encoded binary content. This value should be considered according to the value of Encoding property.
EncodingEnum Encoding
Possible values as per EncodingEnum type definition.
string UserDataHeader
If the message Completed contains the User Data Header (UDH), it will be returned in this field as hexadecimally encoded binary content, for example: "06050415831583". If the message does not have UDH empty string is returned.
string TimeStamp
Date and time according to the SMSC configuration standard.

OnSemaSubmitResponseAsyncReceived

Event triggered on receive of message submission confirmation in asynchronous submit mode.

public delegate void semaSubmitResponseAsyncReceivedEvent(Object Sender, semaSubmitResponseAsyncReceivedEventArgs e);

Description

The event informs about the response to the message, submitted via semaSubmitMessageAsync function. It should be implemented only if semaSubmitMessageAsync is used.

Parameters

Sender

Object sending the event.

e

Object encapsulating event parameters.

uint OperationReference
Identifier of the submit transaction with the SMSC. Allows matching the submission result returned by the event with message submitted using the semaSubmitMessageAsync function.
int Status
Value has the same meaning as the result value returned from the semaSubmitMessage function and is defined as SEMA protocol Operation Result.
string MessageID
String identifier, consistent with the message identifier received from the semaSubmitMessage function.
string TimeStamp
Date and time according to the SMSC configuration standard.

See Also

semaSubmitMessageAsync, semaSubmitResponseAsyncReceivedEvent, semaSubmitResponseAsyncReceivedEventArgs

OnSemaStatusReportReceived

Event triggered on receive of status report.

public delegate void semaStatusReportReceivedEvent(Object Sender, semaStatusReportReceivedEventArgs e);

Description

The event informs about receive of a message delivering status report from the SMSC.

Parameters

Sender

Object sending the event.

e

Object encapsulating event parameters.

string MessageID
String identifier, consistent with the message identifier received from the semaSubmitMessage function.
DateTime MessageTimeStamp
Date and time stamp, assigned on message submission to the SMSC.
string Destination
Usually this is mobile phone number in canonical format. The parameter should be set in accordance with the SMSC operator's instructions.
int DTON
Value denoting Type Of Number.
int DNPI
Value denoting Numbering Plan Identifier.
string Originator
Usually this is is number of the SMSC's account (a short GSM number). This parameter can also be an alphanumeric string or phone number.
int OTON
Value denoting Type Of Number.
int ONPI
Value denoting Numbering Plan Identifier.
int MessageStatus
See SEMA error codes chapter Message Status section for list of possible values.
int DeliveryFailureReason
See SEMA error codes chapter Delivery Failure Reason section for list of possible values.
DateTime TimeStamp
Date and time according to the SMSC configuration standard.

See Also

semaStatusReportReceivedEvent, semaStatusReportReceivedEventArgs

Properties

Connected

Returns information on connection state.

public bool Connected { get; }

Description

If property is true then connection state on TCP/IP level is connected. If property is false then connection has been disconnected on TCP/IP level. Property is useful in implementing various reconnect scenarios.

KeepAliveInterval

Connection keep-alive timing.

public int KeepAliveInterval { get; set; }

Description

Value in seconds denoting time interval between packages keeping the connection alive in case no other packages are exchanged with the SMSC. It should be set according to the SMSC operator's instructions and the speed of Internet connection between the component and the SMSC. Typically, this value amounts to one third of the time after which the SMSC breaks the connection in case of lack of activity. When set to zero keep alive packets are never sent to the SMSC.

ResponseTimeOut

Communication timeout.

public int ResponseTimeOut { get; set; }

Description

Time in seconds, which determines maximum time the component will wait for response from the SMSC. It concerns all protocol level functions. After this time the function returns error code denoting operation timeout.

ImmediateResponse

Status report confirmation mode.

public bool ImmediateResponse { get; set; }

Description

Property decides whether semaStatusReportReceivedEvent event confirms receive of the status report to the SMSC before (true) or after (false) execution of user code in the event handler. If the report is confirmed before SMSC may initiate another status report delivery faster. Contrarywise in the report is confirmed after, if user code inside event fails the status report is not confirmed and will be repeated by the SMSC within some time.