Retrieving Messages from the Fax Archives

A fax archive can hold potentially hundreds of thousands of fax messages. Because fax archives tend to get large, the fax service extended Component Object Model (COM) implementation does not expose the contents of the fax archives as a collection of fax messages. Instead, you can either retrieve an individual message from the archive using its message ID or access messages in the archive in a sequential manner by using a forward-iterating cursor object.

Using a message ID. If you need to retrieve an individual fax message, and you know the message's ID, you can access the message directly in the archive without creating an iterator object. For more information, see FaxIncomingArchive, FaxOutgoingArchive, IFaxIncomingArchive::GetMessage, and GetMessage. For Windows Vista, see FaxAccountIncomingArchive, FaxAccountOutgoingArchive, IFaxAccountIncomingArchive::GetMessage, and IFaxAccountOutgoingArchive::GetMessage.

Using a forward-iterating cursor. If you do not know a particular fax message's ID, if you need to scan the archive, or if you need to access multiple messages in the archive, use the FaxIncomingMessageIterator and FaxOutgoingMessageIterator objects that the extended fax COM implementation provides. These objects are called forward iterators because the functionality they provide is unidirectional movement through the fax archive, from beginning to end, one message at a time. The access these objects provide is called cursor-based because you can access only one message at a time, the message where you position the archive cursor. The FaxIncomingMessageIterator and FaxOutgoingMessageIterator interfaces include methods to set the archive cursor at the first message in the archive, to move the archive cursor to the next message in the archive, and to retrieve the properties of the message under the archive cursor. The interfaces also include a method to retrieve the AtEOF property (the end-of-file marker) for the archive.

To determine the size of the archive, after you create an iterator object, position the archive cursor at the first message in the archive. Then continue to move through the succeeding messages in a sequential manner, counting the messages as you go, until you reach the end of the archive.

For more information, see Fax Folders. The Microsoft Visual Basic example Opening a Fax from the Outgoing Archive demonstrates how to use the message iterator.