Partial Dialing

In partial dialing, the application can use lineMakeCall to allocate a call appearance or to dial just part of the full number. Later, the application can complete dialing using lineDial. Partial dialing is sometimes referred to as incremental dialing or delayed dialing.

When the number provided is incomplete, dialing some of the digits may be delayed by placing a ";" (semicolon) at the end of the number. The lineDial function is used in cases in which the application needs to send address information to the switch on an existing call, such as dialing the address of a party to which the call will be transferred.

Note  An application should make sure that incremental dialing (providing the number in small pieces) is supported before attempting to use it. This support is indicated by the LINEADDRCAPFLAGS_PARTIALDIAL bit in the dwAddrCapFlags member in the LINEADDRESSCAPS structure, which is returned by lineGetAddressCaps.

The main reasons for an application to use partial dialing are if the ? character appears in a dialable address or if the service provider does not support one or more of the call progress detection control characters. These characters, which can occur in a dialable address, are W (wait for dial tone); @ (wait for quiet answer); and $ (wait for calling-card prompt tone). These and all other characters used in address strings are discussed in greater detail in Dialable Addresses.

The provider indicates which "wait for" dial string modifiers it supports in the following bits in the dwDevCapFlags member within the LINEDEVCAPS structure returned by lineGetDevCaps:

• LINEDEVCAPFLAGS_DIALBILLING
• LINEDEVCAPFLAGS_DIALQUIET
• LINEDEVCAPFLAGS_DIALDIALTONE

The ? can be placed in the string (either directly by the application or by the address translator with the lineTranslateAddress function) if it is known that the user needs to listen for an undetectable tone before dialing can proceed. Every service provider should reject a dial string that contains the ? character and let the application deal with it as appropriate. For example, the application could use partial dialing to dial the string, up to but not including the ? character, and then display a dialog to let the user signal when the rest of the dial string should be dialed.

The lineTranslateAddress function returns bits, in the dwTranslateResults member of the LINETRANSLATEOUTPUT structure, that indicate whether any of the four potentially offending modifiers occur in the dialable string output from that translation operation. These bits give the application an idea of whether the dialable string might need to be scanned for unsupported modifiers:

• LINETRANSLATERESULT_DIALBILLING
• LINETRANSLATERESULT_DIALQUIET
• LINETRANSLATERESULT_DIALDIALTONE
• LINETRANSLATERESULT_DIALPROMPT

If the application tries to send an unsupported modifier or a ? to the provider, it receives an error indicating which offending modifier occurred first within the string:

• LINEERR_DIALBILLING
• LINEERR_DIALQUIET
• LINEERR_DIALDIALTONE
• LINEERR_DIALPROMPT

The application can choose to pre-scan dialable strings for unsupported characters. Or it can pass the "raw" string from lineTranslateAddress directly to the provider as part of lineMakeCall (or lineDial or any other function that passes a dialable address as a parameter) and then let the service provider generate an error to tell it which unsupported modifier occurs first in the string.

When the application is told (or finds) that an unsupported dial modifier is in the dialable string, it must take the following steps:

1. Locate the offending modifier in the string.
2. Isolate the characters occurring in the string to the left of the offending modifier.
3. Append a semicolon to the end of the partial string.
4. Reissue the dialing command using the partial string.
5. Prompt the user to listen for the audible tones indicating when it is OK to proceed with dialing.
6. Reissue the remainder of the dialable string (the portion following the offending modifier).

   Note  In step 6 it is possible for another error to occur, because it is possible for multiple unsupported characters to occur within a single dialable string. Therefore, the application should repeat this process to dial the number in stages.