SMSCclientCIMD2
Overview
| Class | SMSCclientCIMD2 |
| Namespace | smscc.CIMD2 |
| Parent | TComponent |
| Interfaces | ISMSCclientCIMD2 |
Methods | |
| tcpConnect | Connect to the SMSC on network protocol (TCP/IP) level. |
| tcpDisconnect | Disconnect from the SMSC on network protocol (TCP/IP) level. |
| cimd2InitializeSession | Login and initialize communication session on CIMD2 protocol level. |
| cimd2SubmitMessage | Submit message to the SMSC. |
| cimd2SubmitMessageEx | Submit message to the SMSC with extended parameter set. |
Events | |
| OnTcpDisconnected | Event triggered on disconnection on network protocol (TCP/IP) level. |
| OnCimd2MessageReceived | Event triggered on message being received from the SMSC. |
| OnCimd2MessageCompleted | Event triggered on multipart message is reconstructed. |
| OnCimd2StatusReportReceived | 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
cimd2InitializeSession
Login and initialize communication session on CIMD2 protocol level.
int cimd2InitializeSession(string UserID, string Password);Parameters
UserID- SMSC user identifier.
Password- SMSC user password.
Returns
If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means CIMD2 protocol's Error Code.
cimd2SubmitMessage
Submit message to the SMSC.
int cimd2SubmitMessage(string Destination, string Originator, string Content, EncodingEnum Encoding, string UserDataHeader, SubmitOption Options, string ExtendedParameters, 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.
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. ExtendedParameters- Allows passing additional parameters to the function call. For the description and syntax of parameters that can be passed this way see Extended Parameters.
TimeStamps- Time of reception of the message to transfer by the SMSC. Used to identify status report returned by the SMSC. The pair TimeStamp and Destination (which uniqueness is guaranteed by the SMSC) is used to match status report with appropriate message submitted.
Returns
If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means CIMD2 protocol's Error Code.
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 OnCimd2StatusReportReceived event.
See Also
cimd2SubmitMessageEx
Submit message to the SMSC with extended parameter set.
int cimd2SubmitMessageEx(string Destination, string Originator, string Content, EncodingEnum Encoding, string UserDataHeader, SubmitOption Options, string TariffClass, string ServiceDescription, string ExtendedParameters, 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.
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. TariffClass- Tariff Class parameter passed to the SMSC on submission. Required by some SMSCs. For more information see CIMD (5.3). The value is passed to the SMSC only when value different from zero is passed through the parameter.
ServiceDescription- Service Description parameter passed to the SMSC on submission. Required by some SMSCs. For more information see CIMD (5.3). The value is passed to the SMSC only when value different from zero is passed through the parameter.
ExtendedParameters- Allows passing additional parameters to the function call. For the description and syntax of parameters that can be passed this way see Extended Parameters.
TimeStamps- Time of reception of the message to transfer by the SMSC. Used to identify status report returned by the SMSC. The pair TimeStamp and Destination (which uniqueness is guaranteed by the SMSC) is used to match status report with appropriate message submitted.
Returns
If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means CIMD2 protocol's Error Code.
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 OnCimd2StatusReportReceived 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 component 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
tcpDisconnect, OnTcpDisconnectedEvent, tcpDisconnectedEventArgs
OnCimd2MessageReceived
Event triggered on message being received from the SMSC.
public delegate void cimd2MessageReceivedEvent (Object Sender, cimd2MessageReceivedEventArgs 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.
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.
string Content- This can be ASCII characters string or hexadecimally encoded binary content. This value should be considered according to the value of cimd2MessageReceivedEventArgs.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.
string ExtendedParameters- Allows to retrieve the additional parameters from the message received. For the description and syntax of parameters that can be retreived this way see Extended Parameters.
See Also
cimd2MessageReceivedEvent, cimd2MessageReceivedEventArgs
OnCimd2MessageCompleted
Event triggered on multipart message is reconstructed.
public delegate void cimd2MessageCompletedEvent (Object Sender, cimd2MessageCompletedEventArgs 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.
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.
string Content- This can be ASCII characters string or hexadecimally encoded binary content. This value should be considered according to the value of cimd2MessageCompletedEventArgs.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.
string ExtendedParameters- Allows to retrieve the additional parameters from the message Completed. For the description and syntax of parameters that can be retreived this way see Extended Parameters.
OnCimd2StatusReportReceived
Event triggered on receive of status report.
public delegate void cimd2StatusReportReceivedEvent (Object Sender, cimd2StatusReportReceivedEventArgs 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.
DateTime MessageTimeStamp- Date and time stamp assigned on message submission by the SMSC.
string Destination- Usually this is mobile phone number in canonical format.
Integer StatusCode- See CIMD2 error codes chapter Status Code section for list of possible values.
int StatusErrorCode- See CIMD2 error codes chapter Status Error Code section for list of possible values.
DateTime TimeStamp- Date and time according to the SMSC configuration standard. If StatusCode denotes correct message delivery, time TimeStamp denotes message delivery time. If the value returned by StatusCode denotes message delivery failure than TimeStamp contains the time of the last attempt to deliver the message.
See Also
cimd2StatusReportReceivedEvent, cimd2StatusReportReceivedEventArgs
Properties
Connected
Returns information on connection state.
public bool Connected { get; }Description
Remarks
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 cimd2StatusReportReceivedEvent 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.