The TranslateAddress function translates an given addess, specified by
the Address parameter, into it's dialable, localized counterpart. The
Address parameter must be in either the canonical address format, or an
arbitrary string of dialable digits (non-canonical). This parameter must
not be empty. If the Address parameter contains a subaddress or name field,
or additional addresses separated from the first address by CR and LF
characters, only the first address is translated.
Example
Labe1l.Caption := hbTapiLine1.TranslateAddress('+49
(89) 12345678');
// Label1.Caption will display 'T0 123456789', if you're dialing
with tone dial from Germany, Munich.
Declaration
function TranslateAddress(Address: String): String;
Description
Canonical Addresses
The canonical address format is intended to be a universally constant directory
number. For this reason, numbers in address books are best stored using canonical
format. The following details concern what is considered canonical for a phone
address.
A canonical phone address is a text string with the following structure:
+ CountryCode Space [(AreaCode) Space] SubscriberNumber
| Subaddress ^ Name CRLF ...
The components of this structure are described in the following table.
Component
Meaning
+
Equivalent to hex 2B. Indicates that the number that follows it uses
the canonical format.
CountryCode
A variably sized string containing one or more of the digits "0" through
"9" (hex 30 through 39, inclusive). The CountryCode is delimited
by the following Space. It identifies the country/region in which the
address is located.
Space
Exactly one space character (hex 20). It is used to delimit the end of
the CountryCode part of an address.
AreaCode
A variably sized string containing zero or more of the digits "0" through
"9" (hex 30 through 39, inclusive). 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 left parenthesis character (28), and be followed
by exactly one right parenthesis character (29) and one space character
(20).
SubscriberNumber
A variably sized string containing one or more of the digits "0" through
"9" (hex 30 through 39, inclusive). It may include other formatting characters
as well, including any of the dialing control characters described in
the Dialable Address Format:
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, nondigit characters in the
subscriber number would include only spaces, periods ("."), and dashes
("-"). Any allowable nondigit characters that appear in the subscriber
number are omitted from the DialableString returned by the ThbTapiLine.TranslateAddress
method.
|
Hex (7C). 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 subaddress information, as for an ISDN subaddress.
Subaddress
A variably sized string containing a subaddress. The string is delimited
by + | ^ CRLF or the end of the address string. During dialing, subaddress
information is passed to the remote party. It can be such things as an
ISDN subaddress or an e-mail address.
^
Hex (5E). 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 variably sized 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
Hex (0D) followed by Hex (0A), 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).
For example, the canonical representation of the main switchboard telephone
number at Microsoft Corporation would be:
+1 (425) 882-8080
Remarks
Please refer to the section "lineTranslateAddress" in TAPI's documentation for a more detailed information.