SMSCserverUCP
Overview
| Class | SMSCserverUCP |
| Namespace | smscs.UCP |
| Parent | TComponent |
| Interfaces | ISMSCserverUCP |
Methods | |
| ucpInitializeServer | Start listening to the incoming connections. |
| ucpFinalizeServer | Stop listening to the incoming connections. |
| tcpAcceptConnection | Accept incomming connection. |
| tcpCloseConnection | Close either incomming or existing connection. |
| tcpCloseAllConnections | Closes all active connections maintained by the component. |
| ucpSendRAW | Send raw UCP message. |
| ucpSendLoginResponse | Send response to the login message. |
| ucpSendDeliverMessage | Deliver message to the client. |
| ucpSendDeliverStatusReport | Deliver status report to the client. |
| ucpSendSubmitMessageResponse | Send response to a submitted message. |
Events | |
| OnTcpConnected | Event triggered on client connection on network protocol (TCP/IP) level. |
| OnTcpDisconnected | Event triggered on client disconnection on network protocol (TCP/IP) level. |
| OnUcpRAWReceived | Event triggered on non interpreted (RAW) message receive. |
| OnUcpLoginReceived | Event triggered on receive of login message. |
| OnUcpDeliverResponseReceived | Event triggered on receive of a response to message delivered to the client. |
| OnUcpSubmitMessageReceived | Event triggered on receive of a message submitted by client. |
| OnUcpSubmitMessageCompleted | Event triggered when multipart message is reconstructed. |
| OnUcpTraceProtocol | Event triggered on every UCP protocol message exchanged between component and the SMSC. |
Properties | |
| KeepAliveInterval | Connection keep-alive timing. |
| ThrottleRate | Message throttling limit parameter. |
Methods
ucpInitializeServer
Start listening to the incoming connections.
int ucpInitializeServer(string LocalHost, int LocalPort, string ExtendedParameters);Parameters
LocalHost- Either numeric or symbolic address of local interface that the component should listen on. In most cases should be set to the address of the local host e.g. "127.0.0.1" or left empty to listen on all interfaces.
LocalPort- Port number on which the component should listen to the incoming connections.
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.
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
ucpFinalizeServer, OnTcpConnected, tcpAcceptConnection, tcpCloseConnection
ucpFinalizeServer
Stop listening to the incoming connections.
int ucpFinalizeServer();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
tcpAcceptConnection
Accept incomming connection.
int tcpAcceptConnection(int ClientID);Parameters
ClientID- Client connection identifier.
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
ucpInitializeServer, tcpCloseConnection, OnTcpConnected
tcpCloseConnection
Close either incomming or existing connection.
int tcpCloseConnection(int ClientID);Parameters
ClientID- Client connection identifier.
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
ucpInitializeServer, OnTcpDisconnected
tcpCloseAllConnections
Closes all active connections maintained by the component.
void tcpCloseAllConnections();See Also
tcpCloseConnection, OnTcpDisconnected
ucpSendRAW
Send raw UCP message.
int ucpSendRAW(uint ClientID, uint TransactionNumber, string OperationClass, uint OperationType, string Payload);Parameters
ClientID- Client connection identifier.
TransactionNumber- Transaction identifier.
OperationClass- UCP command identifier.
OperationType- UCP command identifier.
Payload- Message binary data (except header) in hexadecimal form.
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
ucpSendLoginResponse
Send response to the login message.
int ucpSendLoginResponse(uint ClientID, uint TransactionNumber, ucpResponseType ResponseType, uint ErrorCode, string SystemMessage);Parameters
ClientID- Client connection identifier.
TransactionNumber- Transaction identifier.
ResponseType- Response Type.
ErrorCode- Error Code as defined in Error Code section.
SystemMessage- Readable error message returned to the client.
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
ucpSendDeliverMessage
Deliver message to the client.
int ucpSendDeliverMessage(uint ClientID, uint TransactionNumber, string Destination, string Originator, WideString Content, EncodingEnum Encoding, string UserDataHeader, SubmitOption Options, ref List< uint > TransactionNumbers);Parameters
ClientID- Client connection identifier.
TransactionNumber- Transaction identifier.
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. TransactionNumbers- Identifier of the transaction with the SMSC. Allows matching the submission with return code provided by the OnUcpSubmitResponseAsyncReceived event.
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
OnUcpDeliverResponseReceived, ucpDeliverResponseReceivedEventArgs
ucpSendDeliverStatusReport
Deliver status report to the client.
int ucpSendDeliverStatusReport(uint ClientID, uint TransactionNumber, DateTime DeliveryTimeStamp, string Destination, string Originator, int DeliveryStatus, int ReasonCode, string Text, DateTime TimeStamp);Parameters
ClientID- Client connection identifier.
TransactionNumber- Transaction identifier.
DeliveryTimeStamp- Time stamp which identifies message.
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.
DeliveryStatus- See UCP Error Codes chapter Delivery Status section for list of possible values.
ReasonCode- Failure reason in the process of delivering the message. See UCP Error Codes chapter Reason Code section for list of possible values.
Text- The text or content of the status report message received. In some configurations contains additional information or commentary on error codes returned.
TimeStamp- The time and date at which the short message reached it's final state.
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
OnUcpDeliverResponseReceived, ucpDeliverResponseReceivedEventArgs
ucpSendSubmitMessageResponse
Send response to a submitted message.
int ucpSendSubmitMessageResponse(uint ClientID, uint TransactionNumber, ucpResponseType ResponseType, uint ErrorCode, string Destination, DateTime TimeStamp);Parameters
ClientID- Client connection identifier.
TransactionNumber- Transaction identifier.
ResponseType- Response Type.
ErrorCode- Error Code as defined in Error Code section.
Destination- Message recipient identifier. Usually this is mobile phone number in fully qualified format.
TimeStamp- Time of the reception of the message by the SMSC.
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
Events
OnTcpConnected
Event triggered on client connection on network protocol (TCP/IP) level.
public delegate void tcpConnectedEvent (TObject sender, tcpConnectedEventArgs e);
Description
The event informs that a clietn has connected to the server. It is then up to the server logic to decide whether to accept or reject such connection. In response to the event either tcpAcceptConnection,tcpCloseConnection should be called inside the event code.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to received protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
string RemoteHost- IP address of the remote client that is about to connect to the server. In dotted numeric representation (e.g. "192.168.8.16").
int RemotePort- Port number of the remote client that is about to connect to the server.
See Also
tcpConnectedEvent, tcpConnectedEventArgs, tcpAcceptConnection, tcpCloseConnection
OnTcpDisconnected
Event triggered on client disconnection on network protocol (TCP/IP) level.
public delegate void tcpDisconnectedEvent (TObject 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 ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to received protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
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
tcpDisconnectedEvent, tcpDisconnectedEventArgs
OnUcpRAWReceived
Event triggered on non interpreted (RAW) message receive.
public delegate void ucpRAWReceivedEvent (TObject sender, ucpRAWReceivedEventArgs e);
Description
Event triggered on receive of a UCP message that has not been decoded by any of the functionality serviced by the component.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to received protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
uint TransactionNumber- Identifier of the request/response sequence exchanged between UCP client and server. Response should have the same Transaction Number as request. Transaction Numbers are generated independently by client and server and should be unique for each peer.
string OperationClass- UCP operation can either be a Request or Answer.
int OperationType- UCP operation type defines what protocol message is contained in the frame.
string Payload- Protocol frame (also referred as PDU, Protocol Data Unit) consists of header (which contains Transaction Number, Command ID and Command Status) and message data. This property contains message data part, without header, in hexadecimal representation (each two hexadecimal digits represent one byte of data).
See Also
ucpRAWReceivedEvent, ucpRAWReceivedEventArgs, ucpSendRAW
OnUcpLoginReceived
Event triggered on receive of login message.
public delegate void ucpLoginReceivedEvent (TObject sender, ucpLoginReceivedEventArgs e);
Description
The event informs that the client has issued login message. User can analyze login message credentials and other parameters and decide whether to accept or reject client's communication. In event handler ucpSendLoginResponse should be called to pass response to the client.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to received protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
uint TransactionNumber- Identifier of the request/response sequence exchanged between UCP client and server. Response should have the same Transaction Number as request. Transaction Numbers are generated independently by client and server and should be unique for each peer.
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 TON- int value denoting Type Of Number.
int NPI- int value denoting Numbering Plan Identifier.
string Password- SMSC user password
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
ucpLoginReceivedEvent, ucpLoginReceivedEventArgs, ucpSendLoginResponse
OnUcpDeliverResponseReceived
Event triggered on receive of a response to message delivered to the client.
public delegate void ucpDeliverResponseReceivedEvent (TObject sender, ucpDeliverResponseReceivedEventArgs e);
Description
The event informs that the client has confirmed a message delivered. The same event is fired for both a message and status report. To which message is this confirmation can be determined by SequenceNumber parameter.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to received protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
uint TransactionNumber- Identifier of the request/response sequence exchanged between UCP client and server. Response should have the same Transaction Number as request. Transaction Numbers are generated independently by client and server and should be unique for each peer.
ucpResponseType ResponseType- Defines type of the response according to ucpResponseType.
uint ErrorCode- Error Code as defined in UCP Error Codes chapter Error Code section.
string SystemMessage- In some configurations contains additional information or commentary on error codes returned.
See Also
ucpDeliverResponseReceivedEvent, ucpDeliverResponseReceivedEventArgs
OnUcpSubmitMessageReceived
Event triggered on receive of a message submitted by client.
public delegate void ucpSubmitMessageReceivedEvent (TObject sender, ucpSubmitMessageReceivedEventArgs e);
Description
The event informs that the client has submitted a message to the server. Either ucpSendSubmitMessageResponse should be called to pass response to the client.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to received protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
uint TransactionNumber- Identifier of the request/response sequence exchanged between UCP client and server. Response should have the same Transaction Number as request. Transaction Numbers are generated independently by client and server and should be unique for each peer.
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.
EncodingEnum Encoding- Possible values as per EncodingEnum type definition.
SubmitOption Options- Options that can be set to submitted message as per SubmitOptionEnum type definition. More than one option can be set at the same time by using the OR operator on selected option values.
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.
DateTime DeliveryTime- Contains the message delivery time. Works according to Options parameter. If Options parameter contains the flag soDeliveryTimeRelative then the delivery time is considered relative to the time when message was submitted to the SMSC. If the Options parameter contains the flag soDeliveryTimeAbsolute then the delivery time is considered absolute in the machine local time zone.
DateTime ValidityPeriod- Contains the message validity time. Works according to Options parameter. If Options parameter contains the flag soValidityPeriodRelative then the message validity time is considered relative to the submission to the SMSC. If Options parameter contains the flag soValidityPeriodAbsolute then the message validity time is considered absolute in the machine local time zone. If both options are specified absolute time is set. When set as relative the time the maximum period is 31 days. Anything above wil be shortened to 31 days.
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
ucpSubmitMessageReceivedEvent, ucpSubmitMessageReceivedEventArgs, ucpSendSubmitMessageResponse
OnUcpSubmitMessageCompleted
Event triggered when multipart message is reconstructed.
public delegate void ucpSubmitMessageCompletedEvent (TObject sender, ucpSubmitMessageCompletedEventArgs e);
Description
The event informs that the client has submitted a message which either completes a multipart message or does not need completition.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to Completed protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
uint TransactionNumber- Identifier of the request/response sequence exchanged between UCP client and server. Response should have the same Transaction Number as request. Transaction Numbers are generated independently by client and server and should be unique for each peer.
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.
EncodingEnum Encoding- Possible values as per EncodingEnum type definition.
SubmitOption Options- Options that can be set to submitted message as per SubmitOptionEnum type definition. More than one option can be set at the same time by using the OR operator on selected option values.
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.
DateTime DeliveryTime- Contains the message delivery time. Works according to Options parameter. If Options parameter contains the flag soDeliveryTimeRelative then the delivery time is considered relative to the time when message was submitted to the SMSC. If the Options parameter contains the flag soDeliveryTimeAbsolute then the delivery time is considered absolute in the machine local time zone.
DateTime ValidityPeriod- Contains the message validity time. Works according to Options parameter. If Options parameter contains the flag soValidityPeriodRelative then the message validity time is considered relative to the submission to the SMSC. If Options parameter contains the flag soValidityPeriodAbsolute then the message validity time is considered absolute in the machine local time zone. If both options are specified absolute time is set. When set as relative the time the maximum period is 31 days. Anything above wil be shortened to 31 days.
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.
<> List TimeStamps- Message TimeStamp(s) returned to the SMSC for the messages that form the completed message. They should be used to later deliver Status Reports using ucpSendDeliverStatusReport.
See Also
OnSubmitMessageCompleted, smppSubmitMessageCompletedEventArgs
OnUcpTraceProtocol
Event triggered on every UCP protocol message exchanged between component and the SMSC.
public delegate void ucpTraceProtocolCallback (TObject Sender, ucpTraceProtocolCallbackArgs e);
Description
This event allows to log all messages exchanged on the UCP protocol level between the component and the SMSC. Protocol messages are passed as hexadecimally encoded Protocol Data Units (PDU) which is exact binary representation of protocol message.
Parameters
Sender
Object sending the event.
e
Object encapsulating event parameters.
int ClientID- Component can serve multiple client connections. Each connection has uniqe, numerical identifier. This identifier is used to send responses to Completed protocol messages and to send protocol messages to particular client. If the value returned by ClientID equals -1 then the connection to which event is reported has been disconnected prior to processing of the message.
string FromAddress- Colon separated IP address and port number (IP:Port).
string ToAddress- Colon separated IP address and port number (IP:Port).
int TransactionNumber- Identifier of the request/response sequence exchanged between UCP client and server. Response should have the same Sequence Number as request. Sequence Numbers are generated independently by client and server and should be unique for each peer.
int Operation- This field identifies type of particular UCP message which indicates what operation data is contained within Protocol Data Unit (PDU).
int OperationType- Identifier of the request/response sequence exchanged between UCP client and server.
string PDU- Protocol Data Unit (PDU) message data in hexadecimal representation (each two hexadecimal digits represent one byte of data).
See Also
ucpTraceProtocolCallbackArgs, ucpTraceProtocolCallback
Properties
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.
ThrottleRate
Message throttling limit parameter.
public int ThrottleRate { get; set; }Description
Determines maximum rate of messages submitted to the SMSC per second. If set to any value above 0 component counts number of messages submitted and limits the rate by waiting appropriate time inside ucpSendDeliverMessage, ucpSendDeliverStatusReport, ucpSendSubmitMessageResponse functions. If the value is set to zero component does not limit the rate of delivered messages.