ZfxGetMsgHistory
Get transmission history information for message.
Syntax
ZFERR FAR ZfxGetMsgHistory( ZFSESSIONHANDLE hSession, ZFMSGDIR MsgDir, char FAR *lpszBody, short AddrNum, short fAllEvents, short MaxEntries, short FAR *lpNumEntries, short MsgHistorySize, ZFMSGINFO FAR *lpMsgHistory)
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 |
lpszbody |
Message file body AddrNumWhich addressee events are required for (first addressee is number 1), or 0 to retrieve events for all addressees. |
fAllEvents |
Non zero if events of type ZFEVENT_TRIED are to be included, otherwise only "final state" events are included. |
MaxEntries |
Maximum number of entries to be returned (ie number of elements in the arrays which follow) |
lpNumEntries |
Address 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. |
MsgHistorySize |
Size of structure - should be set to sizeof (ZFMSGHISTORY)lpMsgHistoryAddress of array of 'n' ZFMSGHISTORY structures, where 'n' is the value given by the MaxEntries parameter |
Description
This routine gets a list of the transmission history entries in the CONTROL file for a given message, giving the information about transmission attempts (result, connection time etc).
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.
The fAllEvents flag can be used to specify whether all dial and transmission attempts should be included, or just the final status. If only the final status for a given addressee is required then the function can be called with the fAllEvents flag set to FALSE (0), and a single ZFMSGHISTORY buffer (MaxEntries = 1).
The routine opens and reads the CONTROL file for the message. This is the file that is updated by the Zetafax server while the message is in its queue. It is therefore necessary to protect against calling this routine too frequently while the entry is in the server queue. Use ZfxCheckNewMsgStatus and ZfxGetMsgInfo to wait until the message has completed before calling this routine.
NOTE - this function is supplied for compatibility with version 5 of the Zetafax API only. Version 6 API applications should use ZfxGetMsgHistoryEx .
Return value
The routine returns 0 if successful, otherwise one of the following:
ZFERR_NOT_INITIALISED
ZFERR_INVALID_PARAMETERS
ZFERR_CONTROL_FILE_OPEN_ERROR
ZFERR_CONTROL_FILE_ERROR
ZFERR_CONTROL_FILE_INVALID
Example
#include <stdio.h>
#include <zfapi.h>
...
#define LIST_SIZE 20
ZFMSGHISTORY aMsgHistory[LIST_SIZE];
Err = ZfxGetMsgHistory(hSession, ZFDIR_OUT, "~SEND000", 1, TRUE, LIST_SIZE, &NumEntries, sizeof(ZFMSGHISTORY), MsgHistory);
if (Err != 0)
{
return;
}
if (NumEntries > LIST_SIZE)
{
printf("Total messages %d\n", NumEntries); printf("Displaying first %d\n", LIST_SIZE);
}
for (Entry = 0, Tries = 1; Entry < min(NumEntries, LIST_SIZE); Entry++)
{
switch(aMsgHistory[Entry]->EventType)
{
case ZFEVENT_TRIED: Tries++;
printf("Tried unsuccessfully\n");
break;
case ZFEVENT_SENT_OK:
Tries++;
printf("Sent OK on attempt %d\n" Tries);
printf("Connect time %d secs\n", MsgHistory[Event].ConnectSecs);
break;
case ZFEVENT_SENT_ERROR:
Tries++;
printf("Failed after %d attempts\n", Tries);
printf("Pages sent %d\n", aMsgHistory[Event].Pages);
break;
default:
/* ignore other events */
break;
}
}
Related topics