<< Click to Display Table of Contents >>






Get transmission history information for message.




ZFERR FAR ZfxGetMsgHistoryEx( ZFSESSIONHANDLE hSession, ZFMSGDIR MsgDir, char  FAR *lpszBody, short AddrNum, SHORT fAllEvents, short MaxEntries, short FAR  *lpNumEntries, short MsgHistoryExSize, ZFMSGHISTORYEX FAR *lpMsgHistoryEx)







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


Body of message file to get history forAddrNumWhich 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. MaxEntriesMaximum 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(ZFMSGHISTORYEX)lpMsgHistoryExAddress of array of 'n' ZFMSGHISTORYEX 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 which  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 - this can be done by using the ZfxCheckNewMsgStatus and ZfxGetMsgInfoEx routines to wait until the message has  completed before calling this routine.


Return value


The routine returns 0 if successful, otherwise one of the following:









#include  <stdio.h>

#include <zfapi.h>


#define LIST_SIZE 20



Err = ZfxGetMsgHistoryEx(hSession, ZFDIR_OUT, "~SEND000", 1, TRUE, LIST_SIZE, &NumEntries, sizeof(ZFMSGHISTORYEX),  MsgHistoryEx);


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:


                 printf("Tried  unsuccessfully\n");



         case ZFEVENT_SENT_OK:


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

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



         case ZFEVENT_SENT_ERROR:


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

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



         default: /* ignore other events */





Related topics

Alphabetical reference

Function error returns and reference