The GetGateway method returns information about the
service provider and mail gateway for a specific phone
number, and can be used to determine if a given phone number is
assigned to a mobile device capable of receiving text messages. This
is done by sending an query to a server that will check the phone
number against a database of known providers and the phone numbers
that have been allocated for wireless devices. If the phone number is
valid, information will be returned about the provider that is
responsible for that number along with information about its text
message gateway service.
If the lpszProvider parameter is not NULL, this will
identify a preferred provider for the phone number specified. In the
United States and Canada, most wireless common carriers are required
to provide wireless number portability (WNP) which allows a customer
to continue to use their current phone number even if they switch to
another service provider. This can result in a situation where a
specific phone number is shown as allocated to one provider, but in
actuality that user has switched to a different provider. For example,
a user may have originally purchased a phone and service with AT&T and
then later switched to Verizon, but decided to keep their phone
number. In this case, if Verizon was not specified as the preferred
provider, the library would attempt to send the message to the AT&T
gateway, since that was the original provider who allocated the phone
number.
For most applications, the correct way to handle the situation in
which a user may have switched to a different service provider is to
allow them to select an alternate service provider in your user interface.
For example, you could display a drop-down list of available service
providers, populated using the EnumProviders method. If
they select a preferred provider, then you would pass that value to
this method. If they do not, then specify a NULL pointer and the
default provider will be selected.
This method 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 method 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.