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
Disconnect from the SMSC on network protocol (TCP/IP) level.
void tcpDisconnect();See Also
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
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
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.