|
One of the advantages of TAPI is being able to get pre-set information
directly from Windows, such as whether or not CallWaiting is in effect,
the number to dial an outside line, and more. In Async Professional 2.5,
we added two functions, TranslateAddress and TranslateAddressEx, that
make getting this information easy, but there's a trick: you have to
pass those functions something called a "canonical address." No, it has
nothing to do artillery but you need the right ammunition before you
fire away.
Canonical Addresses
Canonical addresses are ASCII strings in a universal format that can
be converted to a "dialable string", e.g., a string that can be used by
the TApdTapiDevice to dial a number. Microsoft recommends that, because
of the universal formatting, numbers in address books should be stored
using the canonical format.
So, what is the proper format of a canonical address? This syntax
statement and the following descriptions illustrate:
'+ CountryCode Space [(AreaCode)
Space] SubscriberNumber | Subaddress ^ Name CRLF
... '
| Component
|
Meaning |
| + |
ASCII Hex 2B or Decimal 43.
This says that the following number uses the canonical format.
|
| CountryCode
|
A variable-length string
containing one or more of the digits "0" through "9". The
CountryCode is delimited by the following Space. It identifies the
country in which the address is located. The country code is
required and failure to include it will result in improper results
when either TranslateAddress or TranslateAddressEx are called.
|
| Space
|
Exactly one ASCII space
character (0x20 or #32). It is used to delimit the end of the
CountryCode part of an address. |
| AreaCode
|
A string of variable length
containing zero or more of the digits "0" through "9". AreaCode is
the area code part of the address and is optional. If the area code
is present, it must be preceded by exactly one ASCII left
parenthesis character (0x28 or #40), and be followed by exactly one
ASCII right parenthesis character (0x29 or #41) and one ASCII Space
character (0x20 or #32). |
|
SubscriberNumber |
A variable-length string
containing one or more of the digits "0" through "9". It may include
other formatting characters as well, including any of the dialing
control characters described in the Dialable Address Format:
AaBbCcDdPpTtWw*#!,@$?
The subscriber number should not contain the left parenthesis or
right parenthesis character (which are used only to delimit the area
code), nor should it contain the "|", "^", or CRLF characters (which
are used to begin following fields). Most commonly, non-digit
characters in the subscriber number would include only spaces,
periods ("."), and dashes ("-"). Any allowable non-digit characters
that appear in the subscriber number are omitted from the
DialableString returned by the TranslateAddress function, but are
retained in the DisplayableString. |
| | |
ASCII Hex (7C or #124). If
this optional character is present, the information following it up
to the next + | ^ CRLF, or the end of the canonical address string
is treated as sub-address information, as for an ISDN sub-address.
|
| Subaddress
|
A variable-length string
containing a sub-address. The string is delimited by + | ^ CRLF or
the end of the address string. During dialing, sub-address
information is passed to the remote party. It can be such things as
an ISDN sub-address or an e-mail address. |
| ^ |
ASCII Hex (5E or #104). If
this optional character is present, the information following it up
to the next CRLF or the end of the canonical address string is
treated as an ISDN name. |
| Name
|
A variable-length string
treated as name information. Name is delimited by CRLF or the end of
the canonical address string and can contain other delimiters.
During dialing, name information is passed to the remote party.
|
| CRLF
|
ASCII Hex (0D or #13)
followed by ASCII Hex (0A or #10), and is optional. If present, it
indicates that another canonical number is following this one. It is
used to separate multiple canonical addresses as part of a single
address string (inverse multiplexing). |
Here are some examples that should help you understand the basics of
canonical addresses. The following assumes dialing from within the U.S.
| Conditions
|
Canonical Address
|
TranslateAddress Result
|
Local Call,
Tone Dialing |
'+1 555-1212' |
'T 5551212' |
| + 9 for outside line
|
'+1 555-1212' |
'T 9 5551212' |
| + *70 for CallWaiting
|
'+1 555-1212' |
'T *70, 9 5551212'
|
| Long Distance |
'+1 (212) 555-1212'
|
'T 1 212 5551212'
|
| To Australia |
'+1 61 8 333333'
|
'T 011 61 8333333'
|
One thing to remember is that Windows is supplying information based
on the current country settings for the TAPI device being used and the
Regional Settings. The TAPI.HLP file shipped with Borland C++ Builder
has more information on canonical addresses. Unfortunately, this file is
not shipped with the current versions of Delphi (Delphi3), but it is
available on MSDN. |
