ZfxGetMsgList
Get status of all messages for user.
Syntax
ZFERR FAR ZfxGetMsgList( ZFSESSIONHANDLE hSession, ZFMSGDIR MsgDir, short MaxEntries, short FAR *lpNumEntries, ZFMSGINFO FAR *lpMsgInfo)
Parameters
Parameter |
Description |
hSession |
API session handle, as returned by ZfxAPIInit call MsgDirMessage type - ZFDIR_OUT for sent messages, or ZFDIR_IN for received messages |
MaxEntries |
Maximum number of entries to be returned (ie number of elements in the arrays which follow) lpNumEntriesAddress of short integer variable used to return the number of events in the file. Note that the returned value may be larger than the value given for MaxEntries if the buffer was not large enough for all entries. |
lpMsgInfo |
Address of array of 'n' ZFMSGINFO structures, where 'n' is the value given by the MaxEntries parameter. |
Description
This routine gets a list of the entries in the OUT or IN window list for this user, together with information about each one (current status, comment etc). If the program wants to find the status of just one message it is more efficient to call the ZfxGetMsgInfo routine.
If the number of entries in the list exceeds the MaxEntries parameter, then the routine returns information about the first MaxEntries entries, but sets the lpNumEntries parameter to the total number of entries in the list. Be careful therefore to only read the lesser of (MaxEntries) and (lpNumEntries) elements of the array on return. Calling the routine with MaxEntries set to 0 will just return a count of the number of entries.
Entries are added by selecting Send (File menu) in the Zetafax client, by calling the ZfxSendMsgEx routine, or when a new message is received. Entries are removed by selecting Save (File menu) or Delete (File menu) in the Zetafax client or calling ZfxDeleteMsg. A message may also be removed when it completes if it has the "delete on completion" option set, or for an incoming message if it is routed to another user or to an e-mail InBox.
The ZfxCheckNewMsgStatus routine should be used in conjunction with this call if repeatedly checking the status of messages, to prevent reading the INFO file unnecessarily.
NOTE - this function is supplied for compatibility with version 5 of the Zetafax API only. Version 6 API applications should use ZfxGetMsgListEx .
Return value
The routine returns 0 if successful, otherwise one of the following:
ZFERR_NOT_INITIALISED
ZFERR_INVALID_PARAMETERS
ZFERR_INFO_FILE_OPEN_ERROR
ZFERR_INFO_FILE_ERROR
ZFERR_INFO_FILE_INVALID
Example
#include <stdio.h>
#include <zfapi.h>
...
#define LIST_SIZE 20
ZFMSGINFO aMsgInfo[LIST_SIZE];
Err = ZfxGetMsgList(hSession, ZFDIR_OUT, LIST_SIZE, &NumEntries, aMsgInfo);
if (Err != 0)
{
return;
}
if (NumEntries > LIST_SIZE)
{
printf("Total messages %d\n", NumEntries);
printf("Displaying first %d\n", LIST_SIZE);
}
for (Entry = 0; Entry < min(NumEntries, LIST_SIZE); Entry++)
{
printf("Entry %d : %s, status %d\n", Entry, MsgInfo[Entry].szBody, MsgInfo[Entry].Status);
}
Related topics