ZfxAPIInit
Initialise Zetafax API.
Syntax
ZFERR FAR ZfxAPIInit( ZFSESSIONHANDLE *phSession, char FAR *lpszUserName, short fExclusive, ZFERRORPROC *lpErrorProc)
Parameters
Parameter |
Description |
phSession |
Address of variable of type ZFSESSIONHANDLE, used to return the API session handle. This handle should then be passed to other API functions to identify the session. |
lpszUserName |
Zetafax username to use when submitting messages fExclusiveZero if this user is permitted to be logged on elsewhere (either on a normal Zetafax client, or in another API program). |
lpErrorProc |
Address of error message callback function, called when an error occurs with a text string if there is additional information relating to the error. This can be set to NULL if not required.
|
Description
This routine should be called before calling any of the other API functions. The routine may be called more than once by the program if it wishes to log on as more than one user. The paired routine ZfxAPIClosedownshould be called for each handle returned by this function before exiting from the program.
If the fExclusive flag is set (non-zero), then each call to this function may result in a "lock" file being kept open until ZfxAPIClosedown is called. Because most programs have a limit to the total number of files which may be kept open, it is recommended that you only have one session open at a time if fExclusive is set - ie ZfxAPIClosedown is always called before calling ZfxAPIInit again.
Return value
The routine returns 0 if successful, otherwise one of the following:
ZFERR_INVALID_PARAMETERS
ZFERR_NO_ZF_INIT_FILE
ZFERR_INVALID_ZF_INIT_FILE
ZFERR_UNKNOWN_USER
ZFERR_CANNOT_LOG_ON
Example
#include <stdio.h>
#include <zfapi.h>
...
ZFERR Err;
ZFSESSIONHANDLE hSession;
/* Log on as FRED, which sets hSession if ok */
Err = ZfxAPIInit(&hSession, "FRED", TRUE, MyErrorProc);
if (Err == 0)
{
/* call required functions */
...
/* cleanup */
ZfxAPIClosedown(hSession);
}
else
{
printf("Unable to log in as FRED\n");
}
Related topics