The dialable address format describes a number that can be dialed on the given line. A dialable address contains part addressing information and is part navigational in nature. Any input string that does not begin with a "+" character is presumed to be not in canonical format and therefore in dialable address format, and is returned to the application unmodified. A dialable address is an ASCII string with the following structure:
DialableNumber | Subaddress ^ Name CRLF ...
The components of this structure are given in the following table.
| Component | Meaning |
|---|---|
| DialableNumber | Digits and modifiers 0-9 A-D * # , ! W w P p T t @ $ ? ; delimited by | ^ CRLF or the end of the dialable address string. The plus sign (+) is a valid character in dialable strings. It indicates that the phone number is a fully-qualified international number. Within the DialableNumber, note the following definitions: 0-9 A-D * # ASCII characters corresponding to the DTMF and/or pulse digits. |
| ! | ASCII Hex (21). Indicates that a hookflash (one-half second onhook, followed by one-half second offhook before continuing) is to be inserted in the dial string. |
| P p | ASCII Hex (50) or Hex (70). Indicates that pulse dialing is to be used for the digits following it. |
| T t | ASCII Hex (54) or Hex (74). Indicates that tone (DTMF) dialing is to be used for the digits following it. |
| , | ASCII Hex (27). Indicates that dialing is to be paused. The duration of a pause is device specific and can be retrieved from the line's device capabilities. Multiple commas can be used to provide longer pauses. |
| W w | ASCII Hex (57) or Hex (77). An uppercase or lowercase W indicates that dialing should proceed only after a dial tone has been detected. |
| @ | ASCII Hex (40). Indicates that dialing is to "wait for quiet answer" before dialing the remainder of the dialable address. This means to wait for at least one ringback tone followed by several seconds of silence. |
| $ | ASCII Hex (24). Indicates that dialing the billing information is to wait for a "billing signal" (such as a credit card prompt tone). |
| ? | ASCII Hex (3F). Indicates that the user is to be prompted before continuing with dialing. The provider does not actually do the prompting, but the presence of the "?" forces the provider to reject the string as invalid, alerting the application to the need to break it into pieces and prompt the user in-between. |
| ; | ASCII Hex (3B). If placed at the end of a partially specified dialable address string, it indicates that the dialable number information is incomplete and more address information will be provided later. The ";" component is only allowed in the DialableNumber portion of an address. |
| | | ASCII Hex (7C), and is optional. If present, the information following it up to the next + | ^ CRLF, or the end of the dialable 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 the next + | ^ CRLF or the end of the address string. When dialing, subaddress information is passed to the remote party. It can be for an ISDN subaddress, an e-mail address, and so on. |
| ^ | ASCII Hex (5E), and is optional. If present, the information following it up to the next CRLF or the end of the dialable 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 dialable address string. When dialing, name information is passed to the remote party. |
| CRLF | ASCII Hex (0D) followed by ASCII Hex (0A). If present, this optional character indicates that another dialable number is following this one. It is used to separate multiple dialable addresses as part of a single address string (for inverse multiplexing). |
The lineTranslateAddress function and related support functions are used to translate an address from canonical format to dialable format. An application might not use this function to dial a number but it might use it to generate and display for verification a number that could be dialed. Also, it can compute the local time at the destination address from the country code and area code.
The application uses lineTranslateAddress to specify both the line device upon which it intends to dial the call and a canonical address, and the function returns the dialable number and the country code. Because the line device can have specific dialing requirements, it is part of the context needed for an accurate translation.
The user's location also plays a role in address translation. Information related to the current location, such as the country code, area code, and outside line access codes is entered by the user through the Telephony Control Panel. The Subaddress and Name fields, if present in the address, are unmodified by the translation. Alphabetic characters in the number, such as in 1-800-FOR-TAPI, are not translated by the lineTranslateAddress function due to the different standardizations in use in different countries, but they may be translated by applications themselves.
Although an application can use dialable addresses returned by lineTranslateAddress, it is not limited to them and can compose its own dialable numbers.