WinCPICStartup

The WinCPICStartup function allows an application to specify the version of Windows CPI-C required and to retrieve details of the specific Windows CPI-C implementation. This function must be called by an application to register itself with a Windows CPI-C implementation before issuing any further Windows CPI-C calls.

INT WINAPI WinCPICStartup(

Parameters

wVersionRequired

Specifies the version of Windows CPI-C support required. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

lpwcpicdata

A pointer to the CPI-C data structure. The CPICDATA structure is defined as follows:

typedef struct {
....WORD wVersion;
    char szDescription[WCPICDESCRIPTION_LEN+1];
}  CPICDATA, FAR * LPWCPICDATA;
 

where WCPIDESCRIPTION is defined to 127 and the structure members are as follows:

wVersion

The version of Windows CPI-C supported. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

szDescription

The description string describing the CPI-C version supported.

Return Values

The return value specifies whether the application was registered successfully and whether the Windows CPI-C implementation can support the specified version number. If the value is zero, it was registered successfully. Otherwise, the return value is one of the following:

wcpicsysnotrerady

The underlying network subsystem is not ready for network communication.

wcpicvernotsupported

The version of Windows CPI-C support requested is not provided by this particular Windows CPI-C implementation.

wcpicinvalid

The Windows CPI-C version specified by the application is not supported by this DLL.

Remarks

To support future Windows CPI-C implementations and applications that may have functionality differences from Windows CPI-C version 1.0, a negotiation takes place in WinCPICStartup. An application passes to WinCPICStartup the Windows CPI-C version that it can use. If this version is lower than the lowest version supported by the Windows CPI-C DLL, the DLL cannot support the application and the WinCPICStartup call fails. If the version is not lower, however, the call succeeds and returns the highest version of Windows CPI-C supported by the DLL. If this version is lower than the lowest version supported by the application, the application either fails its initialization or attempts to find another Windows CPI-C DLL on the system.

This negotiation allows both a Windows CPI-C DLL and a Windows CPI-C application to support a range of Windows CPI-C versions. An application can successfully use a DLL if there is any overlap in the versions. The following table illustrates how WinCPICStartup works in conjunction with different application and DLL versions.

Details of the actual Windows CPI-C implementation are described in the WHLLDATA structure defined as follows:

typedef struct tagWCPICDATA { WORD wVersion;
            char szDescription[WHLLDESCRIPTION_LEN+1];
            } WCPICDATA, FAR *LPWCPICDATA;
 

Having made its last Windows CPI-C call, an application should call the WinCPICCleanup routine.

Each Windows CPI-C implementation must make a WinCPICStartup call before issuing any other Windows CPI-C calls.