FaxMan SDK Version 4.7
Sending a Fax

This is the main event; you're now actually ready to send a fax. You'll be amazed, first at how little is required of your application to send a fax, then at the ease with which you can create and send complex groupings of faxes.


Sending a fax is as simple as initializing (via the FaxInitSendStruct function) and filling out a SEND_FAX structure and passing it to the FaxSchedule function, like this:




FaxInitSendStruct(pInfo, &sf); // THIS IS REQUIRED!!!

sf.szRecipFax = "1-555-555-5555"; //set the destination fax number

sf.szFileList = "myfax.fmf";  //specify the file(s) to send

FaxSchedule(pInfo, &sf);  //schedule it!


It is a requirement that your application call the FaxInitSendStruct function to initialize the SEND_FAX structure before filling in any of the SEND_FAX fields.


The only things your application is required to fill in are the destination phone number (szRecipFax) and the list of files you wish to send (szFileList), although as you'll discover later you don't even need a file list as long as you include a cover page.


OK, you see what is required to send a fax: not much at all. Now let's start exploring the different options your application has when scheduling a fax. The key to all of this, of course, is the SEND_FAX structure, so we'll start by exploring it in detail.


The SEND_FAX Structure and You

At the end of the DLL interface reference section of this manual is a small section which details the structures used when working with the FaxMan DLL interface. Take a minute to turn to that section and examine the SEND_FAX structure, then we'll cover the interesting members of the structure in some detail.


OK, now that you've had a look at it, we'll get started. The first thing you should notice is that this structure is really divided into two sections: The top section, which contains the items your application can set before calling FaxSchedule, and the bottom part, which contains members filled in by FaxMan during the fax sending process in order to keep your application informed as to the status of the send or receive event. Your application will never alter any of the items in the bottom half of this structure — they are for informational purposes only! Now, let's start investigating the structure members you should be concerned with.



You've already encountered this member - it's just the phone number of the fax machine you wish to send to. This string can contain any of the numbers you would use to dial a phone number, including such things as commas to create pauses, "*70," to turn off call waiting, and others.



Put simply, this is the list of files you wish to include in this fax. This list can consist of just a single filename, as in the example we showed above, or it can be a list of as many files as you wish to chain together. And each of these files can contain as many pages as you like. Effectively, there's no limit to the number of pages a single fax can contain. The following example shows how you can use the "+" character to string together a chain of fax files:




FaxInitSendStruct(pInfo, &sf);

//set the destination fax number

sf.szRecipFax = "1-555-555-5555"; 

sf.szFileList = "coverltr.fmf+myfax.fmf+saleinfo.fmp"; 

FaxSchedule(pInfo, &sf);  //schedule it!


One thing to be careful of is trying to be sure that each of the files you submit to FaxSchedule is a valid FaxMan fax file. If you try to schedule a file list that contains an invalid file, then the fax will not be scheduled (See the section on the ways to create faxes for more info on what constitutes a valid fax file and how to make them).


Finally, the only time that this member can be left NULL is when you're sending a fax which consists solely of a cover page. The rule is that there must be at least one page to fax in order to be able to schedule a fax successfully, so if there's not at least a cover page then you can't send a fax. (Note that you don't always have to include a cover page, but you must always include either a cover page or fill in the szFileList).


nYear, nMonth, nDay, nHour, nMinute, nSecond

These fields specify the time to send the fax. The year ranges from the present to 2038, nMonth ranges from 1-12, nDay ranges from 1-31 (depending on the month, of course), nHour ranges from 0-23, nMinute and nSecond range from 0-59. As long as the server is running when the time to send the fax arrives, the fax will be sent. Your application does not need to be running in order for the fax to be sent. FaxInitSendStruct initializes these fields for an immediate fax send, so there’s no requirement that your application set these unless you want to schedule a fax for a later time.


nRetries, nRetryDelay

These two members specify the number of times to retry the fax on failure and the length of time to wait (in seconds) before retrying the fax. Note that if you set nRetries to 3, the fax will be attempted up to 4 times.



This field is used to identify your faxmodem to the receiving fax machine. This string will generally be displayed by the receiving fax machine during transmission. We recommend that you set this field to the same string used as the ReceiveID for consistency, but it is certainly not a requirement. You may fill in up to 20 characters for the szLocalID.



This field specifies the resolution you wish to use to send the fax, either high or low (standard or enhanced). To send in high resolution, set nSendRes to 1; for low resolution, set it to 0. The default is high resolution.



This is used to define the one-line header at the top of each fax page. This line generally contains such mundane items as the date and time of the fax transmission and the Local ID field. This is discussed in more detail in a subsequent section.



This field is used to define a cover page file to be prepended to the transmitted fax. Details on this are also presented in a subsequent section.



This can be used to specify the port number this fax should be sent on. The default is zero, which indicates that FaxMan should pick the best port to use. If you set this value to a non-existent port number then the fax job will never be sent.


The fields described above all have some kind of impact on the transmission of the fax. The remaining fields exist only for your application's use in such things as banners (the one-line header that is normally printed at the top of faxes) and cover pages. They are described briefly below:


szRecipName — The name of the person the fax is addressed to.

szSubject — The subject of the fax.

szSenderName — The name of the sender of the fax

szComments — Any comments concerning the fax

szSenderCompany — The name of the company sending the fax

szRecipCompany — The name of the company the fax is being sent to

szSenderFax — The fax number of the sending fax machine

szSenderPhone — The phone number of the person sending the fax

szUserData— A field to be used for whatever purpose your app desires


You should note that all of these fields are virtually unlimited in length, although for practical usage in banners or cover pages you will probably want to limit them to reasonable lengths for your application. Just what constitutes a "reasonable length" will probably differ from application to application.



© 2013 Data Techniques, Inc. All Rights Reserved.

Send comments on this topic.