none
TAPI API Programming RRS feed

  • Question

  • In this thread, we will discuss all about TAPI API Programming along with it's function definitions.
    Monday, March 26, 2007 7:52 PM

Answers

  • Telephony Application Programming Interface

    Version 2.2

    Purpose

    The Microsoft® Telephony Application Programming Interface (TAPI) version 2.2 (TAPI/C) allows you to implement communications applications ranging from basic modem control to call centers with multiple agents and switches.

    Where Applicable

    Possible applications include:

    • Basic voice calls on the Public Switched Telephone Network (PSTN)

    • Call center applications capable of tracking multiple agents

    • Modem control

    • PBX control

    • Interactive voice response (IVR) systems

    • Voice mail

    • Detailed phone device control

    Developer Audience

    TAPI/C is designed for use by C/C++ programmers. Previous development experience with telecommunications or other telephony applications is helpful but not necessary.

    Run-time Requirements

    TAPI version 2.2 enables development of communications applications for operating systems that support the Microsoft Win32® API, such as Microsoft Windows® 95, Microsoft Windows® Millennium Edition, or Microsoft Windows® 2000. For information on which operating systems support a particular function, see the Requirements section of the documentation for that function.

    Monday, March 26, 2007 7:54 PM
  • Over time, different versions of TAPI, applications, and service providers may be produced. These new versions can make new definitions, such as for new features, new members in data structures, and new bit fields. Version numbers are therefore necessary to indicate how to interpret various data structures.

    To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, Microsoft Telephony provides a simple version negotiation mechanism for applications. There are two different versions that TAPI and the telephony service provider need to agree on for each line device. The first is the version negotiated with TAPI and the telephony service provider (TSP) Basic and Supplementary Telephony, referred to as the TAPI interface version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and data types used by TAPI's Basic and Supplementary features is defined by the TAPI version, while the extension version determines the format of data structures defined by the vendor-specific extensions.

    The lineNegotiateAPIVersion function negotiates a TAPI version and lineNegotiateExtVersion negotiates the TSP extension version. A single TSP could be capable of handling more than one version, and an application must "fall back" to using an older version if using an older TSP. In lineNegotiateAPIVersion, the dwApiVersion parameter defaults to a value according to version, as follows.

    TAPI
    version
    dwApiVersion
    default value
    1.3 0x00010003
    1.4 0x00010004
    2.0 0x00020000
    2.1 0x00020001
    2.2 0x00020002

    However, TAPI makes this much easier as long as the TSP itself is using a newer version than the application. If the TSP is indeed newer, then TAPI is capable of translating "down" to the application's version. For example, TAPI 2.0 TSPs do not need to be specifically capable of dealing with TAPI version 1.4. If a TAPI 1.4 application is run, TAPI converts all TAPI 2.0 structures and messages into TAPI 1.4 equivalents, or as close as possible. If there is no close approximation in TAPI 1.4, then all TAPI 2.0-specific information will be lost.

    The precise meaning of an extension version is provider-specific. To use a TSP that supports extensions, consult the provider's documentation.

    There are a number of versions of TAPI. While most of these versions involved changes to the TAPI and Telephony Service Provider Interface (TSPI) documentation sets, there are other implications for each version, namely, architectural differences, operating system variations, redistributables, and TSP development issues.

    TAPI version Supported platforms
    1.0 – 1.2 Beta versions that should not be used any longer.
    1.4 Windows 95.
    1.5 Windows CE 1.0.
    2.0 Windows NT® 4.0 SP3.
    2.1 Part of Windows 98 and Windows NT 4.0 SP4. Available as a redistributable for Windows 95.
    2.2 Windows 2000.

    Monday, March 26, 2007 7:57 PM
  • Over time, different versions may exist for TAPI, applications, and service providers for a line or phone. New versions may define new features, new fields to data structures, and so on. Version numbers therefore indicate how to interpret various data structures.

    To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, TAPI provides a simple, two-step version negotiation mechanism for applications. Two different versions must be agreed on by the application, TAPI, and the service provider for each line device. The first is the version number for Basic and Supplementary Telephony and is referred to as the API version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and datatypes used by TAPI's basic and supplementary features is defined by the API version, while the extension version determines the format of the data structures defined by the vendor-specific extensions.

    Version negotiation proceeds in two phases. In the first phase, the API version number is negotiated and the extension identifier associated with any vendor-specific extensions supported on the device is obtained. In the second phase, the extension version is negotiated. If the application does not use any API extensions, it skips the second phase and extensions are not activated by the service provider. If the application does want to use extensions, but the service provider's extensions (the extension identifier) are not recognized by the application, the application should skip the negotiation for extension version as well. Each vendor has its own set of legal (recognized) versions for each set of extension specifications it distributes.

    The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension identifier supported by the line device, returning zeros if no extensions are supported. With this function call, the application provides the API version range it is compatible with. TAPI in turn negotiates with the line's service provider to determine which API version range it supports. TAPI next selects a version number (typically, although not necessarily, the highest version number) in the overlapping version range that the application, the DLL, and the service provider have supplied. This number is returned to the application, along with the extension identifier that defines the extensions available from that line's service provider.

    If the application wants to use the extensions defined by the returned extension identifier, it must first call lineNegotiateExtVersion to negotiate the extension version. In a similar negotiation phase, the application specifies the already agreed-upon API version and the extension version range it supports. TAPI passes this information to the service provider for the line. The service provider checks the API version and the extension version range against its own, and selects the appropriate extension version number, if one exists.

    When the application later calls lineGetDevCaps, it returns a set of device capabilities for the line that correspond to the results of version negotiation. These include the line's device capabilities consistent with the API version and the line's device-specific capabilities consistent with the extension version. The application must specify both of these version numbers when it opens a line. At that point, the application, the DLL, and the service provider are committed to using the agreed-upon versions. If device-specific extensions are not to be used, the extension version should be specified as zero.

    In an environment where multiple applications open the same line device, the first application to open the line device selects the versions for all future applications that want to use the line (service providers do not support multiple versions simultaneously.) Similarly, an application that opens multiple line devices may find it easier to operate all line devices under the same API version number.

    Every function that takes a dwAPIVersion or similar parameter must set this parameter to either the highest API version supported by the application or the API version negotiated using the lineNegotiateAPIVersion or phoneNegotiateAPIVersion function on a particular device. Use the following table as a guide:

    Function Meaning
    lineGetAddressCaps             Use version returned by lineNegotiateAPIVersion.  
    lineGetCountry                      Use highest version supported by the application.  
    lineGetDevCaps                    Use version returned by lineNegotiateAPIVersion.
    lineGetProviderList                Use highest version supported by the application.
    lineGetTranslateCaps             Use highest version supported by the application.
    lineNegotiateAPIVersion        Use highest version supported by the application.
    lineNegotiateExtVersion         Use version returned by lineNegotiateAPIVersion.
    lineOpen                                Use version returned by lineNegotiateAPIVersion.
    lineTranslateAddress              Use highest version supported by the application.
    lineTranslateDialog                 Use highest version supported by the application.
    phoneGetDevCaps                Use version returned by phoneNegotiateAPIVersion.
    phoneNegotiateAPIVersion   Use highest version supported by the application.
    phoneNegotiateExtVersion    Use version returned by phoneNegotiateAPIVersion.
    phoneOpen                           Use version returned by phoneNegotiateAPIVersion.


    Important  When negotiating an API version, always set the high and low version numbers to the range of versions that your application can support. For example, never use 0x00000000 for the low version or 0xFFFFFFFF for the high because these values require that your application support all versions of TAPI, both past and future.

    Tuesday, March 27, 2007 5:46 PM
  • A call handle is the means by which a TAPI 2.2 application identifies a particular communications session. When an application initiates a session, TAPI returns a call handle for use in further operations or queries. When an application is notified of an incoming session, TAPI also passes in a call handle.

    After a session has ended and the session state is idle, the call handle remains valid until the application deallocates the handle or the line is closed. The line might be closed by the application, or it may receive a LINE_CLOSE message. If a line is closed, all call handles to calls on the line instantly become invalid.

    After a call reverts to the idle state, the application is still allowed to read the call's information structure and status. This enables applications to use operations such as lineGetCallInfo to retrieve call information for logging purposes.

    When the application has no further use for the handle of an idle call, it should call lineDeallocateCall to free system-allocated memory related to the call. TAPI allocates memory for each call for each application that has a handle to the call. It is likely that service providers will allocate memory to hold call information as well. Deallocation of an application's call handle allows the library and the service provider to reclaim these memory resources. An application's handle for a call becomes void after a successful deallocation.

    The application must itself free memory related to the call that it allocated for its own purposes.

    Sunday, May 20, 2007 7:57 AM
  • Function

    Description

    lineInitializeEx

    Initializes the TAPI line abstraction for use by the invoking application. Synchronous.

    lineShutdown

    Shuts down the application's use of TAPI's line abstraction. Synchronous.

    Sunday, May 20, 2007 8:01 AM
  • The lineInitializeEx function initializes the application's use of TAPI for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

    LONG WINAPI lineInitializeEx(
      LPHLINEAPP lphLineApp,                            
      HINSTANCE hInstance,                              
      LINECALLBACK lpfnCallback,                        
      LPCSTR lpszFriendlyAppName,                       
      LPDWORD lpdwNumDevs,                              
      LPDWORD lpdwAPIVersion,                           
      LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams 
    );

    Parameters
    ------------
    lphLineApp
    A pointer to a location that is filled with the application's usage handle for TAPI.
    hInstance
    The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process (for purposes of identifying call handoff targets and media mode priorities).
    lpfnCallback
    The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see lineCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
    lpszFriendlyAppName
    A pointer to a null-terminated text string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call-logging purposes. If lpszFriendlyAppName is NULL, the application's module file name is used instead (as returned by the Windows API GetModuleFileName).
    lpdwNumDevs
    A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.
    lpdwAPIVersion
    A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set. TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, thereby allowing the application to detect and adapt to having been installed on a system with a different version of TAPI.
    lpLineInitializeExParams
    A pointer to a structure of type LINEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).
    Return Values
    Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

    LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

    Remarks
    Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

    The Hidden Window mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI verson 1.x applications), TAPI creates a window in the context of the application during the lineInitializeEx or lineInitialize (for TAPI version 1.3 and 1.4 applications) function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage function), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the lineCallbackProc, a pointer to which the application provided as a parameter in its call to lineInitializeEx (or lineInitialize). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the lineShutdown function.

    The Event Handle mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in LINEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call lineGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the lineShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call lineGetMessage and have it block waiting for a message to be queued.

    The Completion Port mechanism is selected by specifying LINEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI sends it using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort member in LINEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey member in LINEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The application retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application has the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a LINEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, it is the application's responsibility to call LocalFree to release the memory used to contain the LINEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling lineShutdown.

    When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

    If LINEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then lineInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

    If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

    The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of any particular TAPI function without first querying their device capabilities by lineGetDevCaps and lineGetAddressCaps.

    Requirements

    Sunday, May 20, 2007 8:04 AM
  • The lineShutdown function shuts down the application's usage of the line abstraction of the API.

    LONG WINAPI lineShutdown(
      HLINEAPP hLineApp  
    );
    Parameters
    hLineApp
    The application's usage handle for the line API.
    Return Values
    Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

    LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

    Remarks
    If this function is called when the application has lines open or calls active, the call handles are deleted and TAPI automatically performs the equivalent of a lineClose on each open line. However, it is recommended that applications explicitly close all open lines before invoking lineShutdown. If shutdown is performed while asynchronous requests are outstanding, those requests are canceled.

    Sunday, May 20, 2007 8:06 AM

All replies

  • Telephony Application Programming Interface

    Version 2.2

    Purpose

    The Microsoft® Telephony Application Programming Interface (TAPI) version 2.2 (TAPI/C) allows you to implement communications applications ranging from basic modem control to call centers with multiple agents and switches.

    Where Applicable

    Possible applications include:

    • Basic voice calls on the Public Switched Telephone Network (PSTN)

    • Call center applications capable of tracking multiple agents

    • Modem control

    • PBX control

    • Interactive voice response (IVR) systems

    • Voice mail

    • Detailed phone device control

    Developer Audience

    TAPI/C is designed for use by C/C++ programmers. Previous development experience with telecommunications or other telephony applications is helpful but not necessary.

    Run-time Requirements

    TAPI version 2.2 enables development of communications applications for operating systems that support the Microsoft Win32® API, such as Microsoft Windows® 95, Microsoft Windows® Millennium Edition, or Microsoft Windows® 2000. For information on which operating systems support a particular function, see the Requirements section of the documentation for that function.

    Monday, March 26, 2007 7:54 PM
  • Over time, different versions of TAPI, applications, and service providers may be produced. These new versions can make new definitions, such as for new features, new members in data structures, and new bit fields. Version numbers are therefore necessary to indicate how to interpret various data structures.

    To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, Microsoft Telephony provides a simple version negotiation mechanism for applications. There are two different versions that TAPI and the telephony service provider need to agree on for each line device. The first is the version negotiated with TAPI and the telephony service provider (TSP) Basic and Supplementary Telephony, referred to as the TAPI interface version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and data types used by TAPI's Basic and Supplementary features is defined by the TAPI version, while the extension version determines the format of data structures defined by the vendor-specific extensions.

    The lineNegotiateAPIVersion function negotiates a TAPI version and lineNegotiateExtVersion negotiates the TSP extension version. A single TSP could be capable of handling more than one version, and an application must "fall back" to using an older version if using an older TSP. In lineNegotiateAPIVersion, the dwApiVersion parameter defaults to a value according to version, as follows.

    TAPI
    version
    dwApiVersion
    default value
    1.3 0x00010003
    1.4 0x00010004
    2.0 0x00020000
    2.1 0x00020001
    2.2 0x00020002

    However, TAPI makes this much easier as long as the TSP itself is using a newer version than the application. If the TSP is indeed newer, then TAPI is capable of translating "down" to the application's version. For example, TAPI 2.0 TSPs do not need to be specifically capable of dealing with TAPI version 1.4. If a TAPI 1.4 application is run, TAPI converts all TAPI 2.0 structures and messages into TAPI 1.4 equivalents, or as close as possible. If there is no close approximation in TAPI 1.4, then all TAPI 2.0-specific information will be lost.

    The precise meaning of an extension version is provider-specific. To use a TSP that supports extensions, consult the provider's documentation.

    There are a number of versions of TAPI. While most of these versions involved changes to the TAPI and Telephony Service Provider Interface (TSPI) documentation sets, there are other implications for each version, namely, architectural differences, operating system variations, redistributables, and TSP development issues.

    TAPI version Supported platforms
    1.0 – 1.2 Beta versions that should not be used any longer.
    1.4 Windows 95.
    1.5 Windows CE 1.0.
    2.0 Windows NT® 4.0 SP3.
    2.1 Part of Windows 98 and Windows NT 4.0 SP4. Available as a redistributable for Windows 95.
    2.2 Windows 2000.

    Monday, March 26, 2007 7:57 PM
  • Thankz buddy.. waiting to learn more on this from you...
    Tuesday, March 27, 2007 11:28 AM
  • Over time, different versions may exist for TAPI, applications, and service providers for a line or phone. New versions may define new features, new fields to data structures, and so on. Version numbers therefore indicate how to interpret various data structures.

    To allow optimal interoperability of different versions of applications, versions of TAPI itself, and versions of service providers by different vendors, TAPI provides a simple, two-step version negotiation mechanism for applications. Two different versions must be agreed on by the application, TAPI, and the service provider for each line device. The first is the version number for Basic and Supplementary Telephony and is referred to as the API version. The other is for provider-specific extensions, if any, and is referred to as the extension version. The format of the data structures and datatypes used by TAPI's basic and supplementary features is defined by the API version, while the extension version determines the format of the data structures defined by the vendor-specific extensions.

    Version negotiation proceeds in two phases. In the first phase, the API version number is negotiated and the extension identifier associated with any vendor-specific extensions supported on the device is obtained. In the second phase, the extension version is negotiated. If the application does not use any API extensions, it skips the second phase and extensions are not activated by the service provider. If the application does want to use extensions, but the service provider's extensions (the extension identifier) are not recognized by the application, the application should skip the negotiation for extension version as well. Each vendor has its own set of legal (recognized) versions for each set of extension specifications it distributes.

    The lineNegotiateAPIVersion function is used to negotiate the API version number to use. It also retrieves the extension identifier supported by the line device, returning zeros if no extensions are supported. With this function call, the application provides the API version range it is compatible with. TAPI in turn negotiates with the line's service provider to determine which API version range it supports. TAPI next selects a version number (typically, although not necessarily, the highest version number) in the overlapping version range that the application, the DLL, and the service provider have supplied. This number is returned to the application, along with the extension identifier that defines the extensions available from that line's service provider.

    If the application wants to use the extensions defined by the returned extension identifier, it must first call lineNegotiateExtVersion to negotiate the extension version. In a similar negotiation phase, the application specifies the already agreed-upon API version and the extension version range it supports. TAPI passes this information to the service provider for the line. The service provider checks the API version and the extension version range against its own, and selects the appropriate extension version number, if one exists.

    When the application later calls lineGetDevCaps, it returns a set of device capabilities for the line that correspond to the results of version negotiation. These include the line's device capabilities consistent with the API version and the line's device-specific capabilities consistent with the extension version. The application must specify both of these version numbers when it opens a line. At that point, the application, the DLL, and the service provider are committed to using the agreed-upon versions. If device-specific extensions are not to be used, the extension version should be specified as zero.

    In an environment where multiple applications open the same line device, the first application to open the line device selects the versions for all future applications that want to use the line (service providers do not support multiple versions simultaneously.) Similarly, an application that opens multiple line devices may find it easier to operate all line devices under the same API version number.

    Every function that takes a dwAPIVersion or similar parameter must set this parameter to either the highest API version supported by the application or the API version negotiated using the lineNegotiateAPIVersion or phoneNegotiateAPIVersion function on a particular device. Use the following table as a guide:

    Function Meaning
    lineGetAddressCaps             Use version returned by lineNegotiateAPIVersion.  
    lineGetCountry                      Use highest version supported by the application.  
    lineGetDevCaps                    Use version returned by lineNegotiateAPIVersion.
    lineGetProviderList                Use highest version supported by the application.
    lineGetTranslateCaps             Use highest version supported by the application.
    lineNegotiateAPIVersion        Use highest version supported by the application.
    lineNegotiateExtVersion         Use version returned by lineNegotiateAPIVersion.
    lineOpen                                Use version returned by lineNegotiateAPIVersion.
    lineTranslateAddress              Use highest version supported by the application.
    lineTranslateDialog                 Use highest version supported by the application.
    phoneGetDevCaps                Use version returned by phoneNegotiateAPIVersion.
    phoneNegotiateAPIVersion   Use highest version supported by the application.
    phoneNegotiateExtVersion    Use version returned by phoneNegotiateAPIVersion.
    phoneOpen                           Use version returned by phoneNegotiateAPIVersion.


    Important  When negotiating an API version, always set the high and low version numbers to the range of versions that your application can support. For example, never use 0x00000000 for the low version or 0xFFFFFFFF for the high because these values require that your application support all versions of TAPI, both past and future.

    Tuesday, March 27, 2007 5:46 PM
  • man keep this thread going Smile
    Sunday, April 29, 2007 5:16 PM
  • A call handle is the means by which a TAPI 2.2 application identifies a particular communications session. When an application initiates a session, TAPI returns a call handle for use in further operations or queries. When an application is notified of an incoming session, TAPI also passes in a call handle.

    After a session has ended and the session state is idle, the call handle remains valid until the application deallocates the handle or the line is closed. The line might be closed by the application, or it may receive a LINE_CLOSE message. If a line is closed, all call handles to calls on the line instantly become invalid.

    After a call reverts to the idle state, the application is still allowed to read the call's information structure and status. This enables applications to use operations such as lineGetCallInfo to retrieve call information for logging purposes.

    When the application has no further use for the handle of an idle call, it should call lineDeallocateCall to free system-allocated memory related to the call. TAPI allocates memory for each call for each application that has a handle to the call. It is likely that service providers will allocate memory to hold call information as well. Deallocation of an application's call handle allows the library and the service provider to reclaim these memory resources. An application's handle for a call becomes void after a successful deallocation.

    The application must itself free memory related to the call that it allocated for its own purposes.

    Sunday, May 20, 2007 7:57 AM
  • Function

    Description

    lineInitializeEx

    Initializes the TAPI line abstraction for use by the invoking application. Synchronous.

    lineShutdown

    Shuts down the application's use of TAPI's line abstraction. Synchronous.

    Sunday, May 20, 2007 8:01 AM
  • The lineInitializeEx function initializes the application's use of TAPI for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

    LONG WINAPI lineInitializeEx(
      LPHLINEAPP lphLineApp,                            
      HINSTANCE hInstance,                              
      LINECALLBACK lpfnCallback,                        
      LPCSTR lpszFriendlyAppName,                       
      LPDWORD lpdwNumDevs,                              
      LPDWORD lpdwAPIVersion,                           
      LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams 
    );

    Parameters
    ------------
    lphLineApp
    A pointer to a location that is filled with the application's usage handle for TAPI.
    hInstance
    The instance handle of the client application or DLL. The application or DLL can pass NULL for this parameter, in which case TAPI uses the module handle of the root executable of the process (for purposes of identifying call handoff targets and media mode priorities).
    lpfnCallback
    The address of a callback function that is invoked to determine status and events on the line device, addresses, or calls, when the application is using the "hidden window" method of event notification (for more information see lineCallbackFunc). This parameter is ignored and should be set to NULL when the application chooses to use the "event handle" or "completion port" event notification mechanisms.
    lpszFriendlyAppName
    A pointer to a null-terminated text string that contains only displayable characters. If this parameter is not NULL, it contains an application-supplied name for the application. This name is provided in the LINECALLINFO structure to indicate, in a user-friendly way, which application originated, or originally accepted or answered the call. This information can be useful for call-logging purposes. If lpszFriendlyAppName is NULL, the application's module file name is used instead (as returned by the Windows API GetModuleFileName).
    lpdwNumDevs
    A pointer to a DWORD-sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.
    lpdwAPIVersion
    A pointer to a DWORD-sized location. The application must initialize this DWORD, before calling this function, to the highest API version it is designed to support (for example, the same value it would pass into dwAPIHighVersion parameter of lineNegotiateAPIVersion). Artificially high values must not be used; the value must be accurately set. TAPI translates any newer messages or structures into values or formats supported by the application's version. Upon successful completion of this request, this location is filled with the highest API version supported by TAPI, thereby allowing the application to detect and adapt to having been installed on a system with a different version of TAPI.
    lpLineInitializeExParams
    A pointer to a structure of type LINEINITIALIZEEXPARAMS containing additional parameters used to establish the association between the application and TAPI (specifically, the application's selected event notification mechanism and associated parameters).
    Return Values
    Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

    LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

    Remarks
    Applications must select one of three mechanisms by which TAPI notifies the application of telephony events: Hidden Window, Event Handle, or Completion Port.

    The Hidden Window mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism (which is the only mechanism available to TAPI verson 1.x applications), TAPI creates a window in the context of the application during the lineInitializeEx or lineInitialize (for TAPI version 1.3 and 1.4 applications) function, and subclasses the window so that all messages posted to it are handled by a WNDPROC in TAPI itself. When TAPI has a message to deliver to the application, TAPI posts a message to the hidden window. When the message is received (which can happen only when the application calls the Windows GetMessage function), Windows switches the process context to that of the application and invokes the WNDPROC in TAPI. TAPI then delivers the message to the application by calling the lineCallbackProc, a pointer to which the application provided as a parameter in its call to lineInitializeEx (or lineInitialize). This mechanism requires the application to have a message queue (which is not desirable for service processes) and to service that queue regularly to avoid delaying processing of telephony events. The hidden window is destroyed by TAPI during the lineShutdown function.

    The Event Handle mechanism is selected by specifying LINEINITIALIZEEXOPTION_USEEVENT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, TAPI creates an event object on behalf of the application, and returns a handle to the object in the hEvent member in LINEINITIALIZEEXPARAMS. The application must not manipulate this event in any manner (for example, must not call SetEvent, ResetEvent, CloseHandle, and so on) or undefined behavior results; the application can only wait on this event using functions such as WaitForSingleObject or MsgWaitForMultipleObjects. TAPI signals this event whenever a telephony event notification is pending for the application; the application must call lineGetMessage to fetch the contents of the message. The event is reset by TAPI when no events are pending. The event handle is closed and the event object destroyed by TAPI during the lineShutdown function. The application is not required to wait on the event handle that is created; the application could choose instead to call lineGetMessage and have it block waiting for a message to be queued.

    The Completion Port mechanism is selected by specifying LINEINITIALIZEEXOPTION_USECOMPLETION PORT in the dwOptions member in the LINEINITIALIZEEXPARAMS structure. In this mechanism, whenever a telephony event needs to be sent to the application, TAPI sends it using PostQueuedCompletionStatus to the completion port that the application specified in the hCompletionPort member in LINEINITIALIZEEXPARAMS, tagged with the completion key that the application specified in the dwCompletionKey member in LINEINITIALIZEEXPARAMS. The application must have previously created the completion port using CreateIoCompletionPort. The application retrieves events using GetQueuedCompletionStatus. Upon return from GetQueuedCompletionStatus, the application has the specified dwCompletionKey written to the DWORD pointed to by the lpCompletionKey parameter, and a pointer to a LINEMESSAGE structure returned to the location pointed to by lpOverlapped. After the application has processed the event, it is the application's responsibility to call LocalFree to release the memory used to contain the LINEMESSAGE structure. Because the application created the completion port (thereby allowing it to be shared for other purposes), the application must close it; the application must not close the completion port until after calling lineShutdown.

    When a multithreaded application is using the Event Handle mechanism and more than one thread is waiting on the handle, or the Completion Port notification mechanism and more than one thread is waiting on the port, it is possible for telephony events to be processed out of sequence. This is not due to the sequence of delivery of events from TAPI, but would be caused by the time slicing of threads or the execution of threads on separate processors.

    If LINEERR_REINIT is returned and TAPI reinitialization has been requested, for example as a result of adding or removing a telephony service provider, then lineInitializeEx requests are rejected with this error until the last application shuts down its usage of the API (using lineShutdown), at which time the new configuration becomes effective and applications are once again permitted to call lineInitializeEx.

    If the LINEERR_INVALPARAM error value is returned, the specified hInstance parameter is invalid.

    The application can refer to individual line devices by using line device identifiers that range from zero to dwNumDevs minus one. An application should not assume that these line devices are capable of any particular TAPI function without first querying their device capabilities by lineGetDevCaps and lineGetAddressCaps.

    Requirements

    Sunday, May 20, 2007 8:04 AM
  • The lineShutdown function shuts down the application's usage of the line abstraction of the API.

    LONG WINAPI lineShutdown(
      HLINEAPP hLineApp  
    );
    Parameters
    hLineApp
    The application's usage handle for the line API.
    Return Values
    Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:

    LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

    Remarks
    If this function is called when the application has lines open or calls active, the call handles are deleted and TAPI automatically performs the equivalent of a lineClose on each open line. However, it is recommended that applications explicitly close all open lines before invoking lineShutdown. If shutdown is performed while asynchronous requests are outstanding, those requests are canceled.

    Sunday, May 20, 2007 8:06 AM
  • Very good info my frined. It will take time to digest; )
    Sunday, May 20, 2007 11:02 AM