| |
| BOOL SendMessage( |
| |
DWORD dwServiceType, |
|
| |
LPCTSTR lpszProvider, |
|
| |
LPCTSTR lpszPhoneNumber, |
|
| |
LPCTSTR lpszSender, |
|
| |
LPCTSTR lpszMessage |
|
| ); |
| BOOL SendMessage( |
| |
LPSMSSERVICE lpService, |
|
| |
LPSMSMESSAGE lpMessage |
|
| ); |
The SendMessage method sends a text message to the specified
mobile device.
Parameters
- dwServiceType
- An unsigned integer value which identifies the type of service
being used to send the message. Currently there is only one valid
service type, SMS_SERVICE_SMTP which sends the message to a
mail gateway provided by the wireless service provider. This
parameter is included for future expansion when multiple alternative
services may be used to send the message.
- lpszProvider
- A pointer to a string that identifies the
wireless service provider that is responsible for the specified
phone number. If the service provider is unknown, this parameter can
be NULL or an empty string. In that case, the default provider for
the phone number will be used.
- lpszPhoneNumber
- A pointer to a string that specifies the phone
number for the mobile device. This can be a standard E.164 formatted
number or an unformatted number. Any extraneous whitespace,
punctuation or other non-numeric characters in the string will be
ignored. This parameter cannot be NULL.
- lpszSender
- A pointer to a string which identifies the
sender of the message and should specify a valid email address. If
the recipient replies to the message, the reply will be sent to this
address. This parameter
cannot be NULL.
- lpszMessage
- A pointer to a null terminated string that contains the message
to be sent to the recipient. In most cases, a message should not
exceed 160 characters in length, although some service providers may
accept longer messages. If a message exceeds the maximum number of
characters accepted by a service provider, the message may be
ignored or it may be split into multiple messages.
- lpService
- A pointer to an SMSSERVICE
structure that identifies the messaging service that will be used to
send the text message. The default service sends the message through
the mail server gateway for the wireless service provider associated
with the recipient's phone number. This parameter cannot be NULL.
- lpMessage
- A pointer to an SMSMESSAGE
structure that contains information about the message to be sent,
including the sender, the recipient and the text message itself.
This parameter cannot be NULL.
Return Value
If the method succeeds, the return value is non-zero. If the method fails, the
return value is zero. To get extended error information, call GetLastError.
Remarks
The SendMessage method is used to send a text message
to a mobile device. This API is designed to support multiple
methods of sending text messages, with the default method sending the
message through a server gateway established by the wireless service
provider.
SMS_SERVICE_SMTP
This message service sends the message through the wireless service
provider's mail gateway using the SMTP protocol. However, it
is important to note that many of these gateways will not accept
messages from a client that is connected to them using a residential
Internet service provider. If the application is being run on a system
that uses a residential provider, that service provider may also block
outbound connections to all mail servers other than their own. These
anti-spam measures typically require that most end-user applications
specify a relay mail server rather than submitting the message directly to
the wireless provider's gateway.
Because most wireless carriers in the United States and Canada must
provide for wireless number portability, there is the possibility that the
provider information returned may no longer correspond to the
telephone number. It is recommended that you provide your end-user
with the ability to specify an alternate preferred provider to use
when sending the text message. For more information, refer to the
GetGateway method.
This service also sends an HTTP query to the server api.sockettools.com
to obtain information about the phone number and wireless service provider.
This requires that the local system can establish a standard network
connection over port 80. If the client cannot connect to the server,
the function will fail and an appropriate error will be returned. The
server imposes a limit on the maximum number of connections that can
be established and the maximum number of requests that can be issued
per minute. If this method is called multiple times over a short
period, the library may also force the application to block briefly.
Server responses are cached per session, so calling this method
multiple times using the same phone number will not increase the
request count.
Requirements
Minimum Desktop Platform: Windows 7 Service Pack 1
Minimum Server Platform: Windows Server 2008 R2 Service Pack 1
Header File: cstools11.h
Import Library: cstxtv11.lib
Unicode: Implemented as Unicode and ANSI versions
See Also
EnableRelay,
GetGateway,
GetProvider,
SMSMESSAGE,
SMSSERVICE
|
|