|
|
|
|
A Windows application accesses CSV using the following functions:
Issues a verb. The verb blocks; that is, the application's thread is suspended until CSV has finished processing the verb and returned the results. This has the same effect as WinCSV.
Registers the application as a Windows CSV user, and determines whether the CSV software supports the level of function required by the application.
Issues a verb. The verb blocks; that is, the application's thread is suspended until CSV has finished processing the verb and returned the results. This has the same effect as ACSSVC_C.
Issues a verb. With the exception of TRANSFER_MS_DATA, the verb blocks; processing is the same as for the WinCSV entry point. The TRANSFER_MS_DATA verb normally completes asynchronously and does not block; CSV indicates the completion by posting a message to the application window.
Unregisters the application when it has finished using CSV.
Generates a printable character string for the primary and secondary return codes obtained on a CSV verb.
The entry points are defined in the Windows CSV header file wincsv.h. This file is installed in the subdirectory /sdk within the directory where you installed the Windows Client software.
The application must call WinCSVStartup before attempting to issue any verbs using the WinCSV or WinAsyncCSV calls. It then issues verbs using either WinAsyncCSV (asynchronous) or WinCSV (synchronous). If a verb returns with return codes that indicate an error, the application can use GetCsvReturnCode to obtain a text string representation of these return codes, which can be used to generate standard error messages.
When the application has finished issuing verbs using the WinCSV or WinAsyncCSV calls, it must call WinCSVCleanup before terminating; it must not attempt to issue any more verbs after calling WinCSVCleanup.
The following sections describe these functions.
The application uses this function to issue a verb. The verb blocks; that is, the application's thread is suspended until CSV has finished processing the verb and returned the results.
For compatibility with other CSV implementations, SNAP-IX also provides the entry points ACSSVC_P and ACSSVC, which can be used in the same way as ACSSVC_C. The entry points are defined in the CSV header file sdk/wincsv.h.
void ASCCVC_C (
void * vcbptr
)
The only parameter passed to the function is the address of a verb control
block (VCB). The VCB is a structure made up of variables that identify the
verb to be executed, supply information to be used by the verb, and contain
information returned by the verb when execution is complete. Each verb has
its own VCB structure, which is declared in the header file sdk/wincsv.h
delivered with SNAP-IX. Use
The CSV VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The function does not return a value.
The application uses this function to register as a Windows CSV user, and to determine whether the CSV software supports the Windows CSV version that it requires.
int WINAPI LOADDS WinCSVStartup (
WORD wVersionRequired,
WCSVDATA far * lpData
);
typedef struct
{
WORD wVersion;
char szDescription[128];
} WCSVDATA;
The supplied parameter is:
The version of Windows CSV that the application requires. SNAP-IX supports version 1.0.
The low-order byte of this parameter specifies the major version number, and the high-order byte specifies the minor version number. For example:
| Version | wVersionRequired |
| 1.0 | 0x0001 |
| 1.1 | 0x0101 |
| 2.0 | 0x0002 |
If the application can use more than one version, it should specify the highest version that it can use.
The return value from the function is one of the following:
The application was registered successfully, and the Windows CSV software
supports either the version number specified by the application or a lower
version. The application should check the version number in the
The version number specified by the application was lower than the lowest version supported by the Windows CSV software. The application was not registered.
The SNAP-IX software has not been started, or the local node is not active. The application was not registered.
If the return value from WinCSVStartup is zero,
the
The Windows CSV version number that the software supports, in the same format as the wVersionRequired parameter (defined previously). SNAP-IX supports version 1.0.
If the software supports the version number requested by the application, this parameter is set to the same value as the wVersionRequired parameter; otherwise it is set to the highest version that the software supports, which will be lower than the version number supplied by the application. The application must check the returned value and take action as follows:
If the returned version number is the same as the requested version number, the application can use this Windows CSV implementation.
If the returned version number is lower than the requested version number, the application can use this Windows CSV implementation but must not attempt to use features that are not supported by the returned version number. If it cannot do this because it requires features not available in the lower version, it should fail its initialization and not attempt to issue any CSV verbs.
A text string describing the Windows CSV software.
The application uses this function to issue a verb, which blocks until verb processing is completed.
void WINAPI LOADDS WinCSV (
long vcbptr
);
The only parameter to the function is a pointer to the VCB structure
for the verb. This is defined as a long integer, and so needs to be cast from
a pointer to a long integer. For the definition of the VCB structure for each
verb, see Common Service Verbs Reference. The CSV VCBs contain many parameters marked as To set the VCB contents to zero, use memset: memset(vcb, 0, sizeof(vcb));Note
reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
The function does not return a value. When the call returns, the application should check the primary_rc and secondary_rc parameters in the VCB structure to determine whether the verb completed successfully. For information about the parameters returned in the VCB structure, see the descriptions of individual verbs in Common Service Verbs Reference.
The application uses this function to issue a verb.
For TRANSFER_MS_DATA, the verb may complete asynchronously; CSV will indicate the completion by posting a message to the application's window handle. All other verbs complete synchronously.
Before using the WinAsyncCSV call for the first time, the application must use RegisterWindowMessage to obtain the message identifier that CSV will use for messages indicating asynchronous verb completion. For more information, see Windows Considerations.
HANDLE WINAPI LOADDS WinAsyncCSV (
HWND hWnd,
long vcbptr
);
The supplied parameters are:
A window handle that CSV will use to post a message indicating asynchronous verb completion.
A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer. For more information about the VCB structure and on its usage for individual verbs, see Common Service Verbs Reference.
The CSV VCBs contain many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
If the function was successful, the return value is a handle. When the verb later completes, CSV uses this handle as an identifier in the message passed to the application's window procedure (for more information, see Usage).
A return value of 0 indicates that the function call was not accepted.
For all verbs other than TRANSFER_MS_DATA, the function operates in the same way as the WinCSV entry point (described in the previous section), and does not return a value. When the call returns, the application should check the primary_rc and secondary_rc parameters in the VCB structure to determine whether the verb completed successfully.
Before using WinAsyncCSV for the first time, the application must use the RegisterWindowMessage call to obtain the message identifier that CSV will use for messages indicating asynchronous verb completion. RegisterWindowMessage is a standard Windows function call, not specific to CSV; refer to your Windows documentation for more information about the function. (There is no need to issue the call again before subsequent verbs; the returned value will be the same for all calls issued by the application.)
The application must pass the string WinAsyncCSV
to the
function; the returned value is a message identifier, as described below.
Each time a verb that was issued using the WinAsyncCSV entry point completes asynchronously, CSV posts a message to the window handle specified on the WinAsyncCSV call. The format of the message is as follows:
The message identifier is the value returned from the RegisterWindowMessage call.
The lParam argument contains the address of the VCB that was supplied to the original WinAsyncCSV call; the application can use this address to access the returned parameters in the VCB structure.
The wParam argument contains the handle that was returned to the original WinAsyncCSV call.
The application uses this function to unregister as a Windows CSV user, after it has finished issuing verbs.
BOOL WINAPI LOADDS WinCSVCleanup (void);
No parameters are supplied for this function.
The return value from the function is one of the following:
The application was unregistered successfully.
An error occurred during processing of the call, and the application was not unregistered. Check the log files for messages indicating the cause of the failure.
This call returns a printable character string interpreting the return codes from a supplied VCB. The string can be used to generate application error messages for return codes other than AP_OK.
This call is designed to provide strings for display to the end user of an application. For return codes indicating configuration problems or user errors (for example if a required component is not configured or not started), the string should provide sufficient information to help the user correct the problem. For return codes indicating application errors (for example, if the application has issued a verb that is not valid or failed to supply a required parameter), the user will not generally be able to correct the problem; in these cases, the string may be meaningful only to an application developer.
int WINAPI LOADDS GetCsvReturnCode (
struct svc_hdr FAR * vcbbptr,
unsigned int buffer_length,
unsigned char FAR * buffer_addr
);
typedef struct svc_hdr
{
unsigned short opcode; /* Verb identifying operation code. */
unsigned char opext; /* Verb extension code - reserved. */
unsigned char reserv2; /* Reserved. */
unsigned short primary_rc; /* Primary return code from verb. */
unsigned long secondary_rc; /* Secondary (qualifying) return code. */
The supplied parameters are:
A pointer to the VCB structure for the verb. For more information about the VCB structure and on its usage for individual verbs, see Common Service Verbs Reference.
The length (in bytes) of the buffer supplied by the application to hold the returned data string. The recommended length is 256 bytes.
The address of the buffer supplied by the application to hold the returned data string.
The return value from the function is one of the following:
The function completed successfully.
CSV could not read from the supplied VCB, or could not write to the supplied data buffer.
The supplied data buffer is too small to hold the returned character string.
The dynamic link library (CSVSTR32.DLL) which generates the returned character strings for this function, could not be loaded.
If the return value is 0x00000000, the returned character string is in the buffer identified by the buffer_addr parameter. This string is terminated by a null character (binary zero), but does not include a trailing new-line (\n) character.
|
|
|
 |
|