TAPI, Don't Lose that Number
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:


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.

This site is not affiliated, endorsed, or otherwise associated with the entity formerly known as TurboPower Software. The owners and maintainers of Aprozilla.com were merely meager employees of the aforementioned organization, providing this site out of the pure goodness of their collective hearts. SourceForge.net Logo

Last updated: July 22, 2003.