<< Click to Display Table of Contents >>






Get transmission history information for message.




ZFERR FAR ZfxGetMsgHistory( ZFSESSIONHANDLE hSession, ZFMSGDIR MsgDir, char FAR  *lpszBody, short AddrNum, short fAllEvents, short MaxEntries, short FAR  *lpNumEntries, short MsgHistorySize, ZFMSGINFO FAR *lpMsgHistory)







API session handle, as returned by ZfxAPIInit  call MsgDirMessage type - ZFDIR_OUT for sent messages, or ZFDIR_IN for  received messages


Message file body AddrNumWhich addressee events are required for (first addressee is  number 1), or 0 to retrieve events for all addressees.


Non zero if events of type ZFEVENT_TRIED are to be included, otherwise only "final state" events are included.


Maximum number of entries to be returned (ie number of  elements in the arrays which follow)


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.


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





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:  









#include  <stdio.h>

#include <zfapi.h>


#define LIST_SIZE 20



Err = ZfxGetMsgHistory(hSession, ZFDIR_OUT, "~SEND000", 1, TRUE, LIST_SIZE, &NumEntries, sizeof(ZFMSGHISTORY),  MsgHistory);

if (Err != 0)




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++)





         case ZFEVENT_TRIED: Tries++;

                 printf("Tried  unsuccessfully\n");



         case ZFEVENT_SENT_OK:


                       printf("Sent  OK on attempt %d\n" Tries);

                       printf("Connect  time %d secs\n", MsgHistory[Event].ConnectSecs);



         case ZFEVENT_SENT_ERROR:


                       printf("Failed  after %d attempts\n", Tries);

                 printf("Pages  sent %d\n", aMsgHistory[Event].Pages);




               /*  ignore other events */





Related topics

Alphabetical reference

Function error returns and reference