More on Controlling Windows Fax Services Using VB.Net

Welcome to the second part of this article about controlling Windows 2003 fax services through a Visual Basic.Net application. In this article, you’ll learn how to get some information from a fax server and write it to a text file. You will also learn how to submit a job to a server.

Background

If you haven’t already done the steps outlined in the first article you will need to complete those before you go any further. If you have already completed them you should have a working Windows 2003 fax server, and a Visual Basic project that can connect to this server using the fxscomex.dll library. At the moment the code we have written does not really do anything very useful; it just proves that we can connect to the server and view/change its properties.

Now Let’s do Something Useful 

As I just mentioned, the application at the moment won’t really do anything useful. Here we are going to write some code that will get some status information off the fax server and write it to a text file. Add a new button to the project, and in its click event, place the following code. What the code is actually doing will be discussed shortly.

Dim objFaxServer As New FAXCOMEXLib.FaxServer   ‘Fax server object

Dim objFaxActivity As FAXCOMEXLib.IFaxActivity ‘Fax activity Object

Dim collFaxDevices As FAXCOMEXLib.FaxDevices   ‘Fax devices object

Dim intTotJobCnt As Integer                     ‘Job and device count

Dim objBalFileWritter As StreamWriter          ‘object to write text

 

‘connect to the fax server.

objFaxServer.Connect("fax-server1")

 

‘work out how many jobs are on the server by adding up the outgoing and queued

objFaxActivity = objFaxServer.Activity

 

‘Refresh the activity object

objFaxActivity.Refresh()

 

‘get the current numbers

intTotJobCnt = objFaxActivity.OutgoingMessages + objFaxActivity.QueuedMessages

 

‘now write it out to the bal file along with the no of modems on this server

collFaxDevices = objFaxServer.GetDevices

  

‘open the file for writing and put the message into it on a new line

objBalFileWritter = File.AppendText("c:num_jobs.log")

objBalFileWritter.WriteLine("Time:" & Now())

objBalFileWritter.WriteLine("Modems:" & collFaxDevices.Count)

objBalFileWritter.WriteLine("Total Faxes:" & intTotJobCnt)

objBalFileWritter.WriteLine("Outgoing: " & objFaxActivity.OutgoingMessages)

objBalFileWritter.WriteLine("Queued: " & objFaxActivity.QueuedMessages)

objBalFileWritter.WriteLine("Incoming: " & objFaxActivity.IncomingMessages)

objBalFileWritter.Close()

{mospagebreak title=What is the Code Doing?}

The first five lines are just our object and variable declarations. The first object (objFaxServer) is our actual connection to the fax server. As discussed in the first article, all the methods we need when controlling the fax services are in FAXCOMEXLib.

Next, we have our activity object called objFaxActivity. This will let us ask the fax service about what active jobs it is currently handling. Our last object is collFaxDevices. This gives us the number of physical fax devices that the fax server is using. These are normally modems but could be ISDNs or others depending on your setup.

The final declaration lines are just a variable we will use to keep track of the number of jobs and our streamwriter object so we can write the values out to a file.

Next, we use our fax server object, and connect it to our fax server. In a production application you should enclose this statement in a Try/Catch in order to gracefully handle any exceptions, the main one here being that you can’t see the server or don’t have permissions to connect to it.

Next we set the activity object we created to the server object. This will now allow us to query that server for activity, so the first thing we do after that is use the refresh method to get all the latest information.

Using our newly created activity object, we then add together its QueuedMessages and OutgoingMessages and hold them in the count variable. This number will tell us how many jobs are currently being sent out from the server, and how many are waiting to be sent.

We then set our devices object to be the number of devices on the server to which we have attached. Now that we have all the information available to us, we can write it out to our file.

First of all we set our StreamWriter to create a new file (c:num_jobs.txt) and append text to it. Then, line by line we write out the current time, the number of modems, the total number of faxes being and waiting to be sent, the number of current outgoing jobs, the number of queued jobs and the number of incoming jobs.

Run the application in Visual Studio, and hit the new button. If all has gone according to plan you should now have a file similar to this one at c:num_jobs.txt:

Time: 11/07/2007 11:38:22

Modems:4

Total Faxes:1

Outgoing: 1

Queued: 0

Incoming: 0

While information like this might not be of too much use, you now should have all the code you need to get overall job information from the server.

I have used this information in the past when load balancing more than one fax server. Before sending any new jobs I look at a file similar to this on all my fax servers, decide which one is the quietest and send my new job to that one.

{mospagebreak title=Submitting a Job to the Server}

Ok, now that we know how to get information from the server, it’s time to try to send a fax. We are going to send a signal page job from our system, and use one of the built-in cover pages.

You can add your own cover pages easily enough. Just open the Fax services manager on the server, and then right click on Cover page, new, cover page. This will launch the fax page editor and let you design your own cover page. You can add your company’s logo and other details, and also drop in components that will be replaced with the recipient’s name, number, and so forth when the fax is sent.

Anyway, create another button on your form in Visual Studio, and add this code to it. I will explain it line by line in the next section.

Dim objFaxServer As New FAXCOMEXLib.FaxServer    ‘connection to the server

Dim objFaxDocument As New FAXCOMEXLib.FaxDocument ‘fax document to send

Dim strFaxPDFtoSend As String

 

‘local document to send

strFaxPDFtoSend = "c:TestFax.pdf"

 

Try

   ‘now we have all the info, we can try and send the job out

   ‘Connect to the fax server

   objFaxServer.Connect("fax-svr1")

   ‘Set the fax body  

   objFaxDocument.Body = strFaxPDFtoSend

 

   ‘Name the document

   objFaxDocument.DocumentName = "Fax from Test Application"

   ‘Set the fax priority

   objFaxDocument.Priority = FAXCOMEXLib.FAX_PRIORITY_TYPE_ENUM.fptNORMAL

   ‘Add the recipient with the fax no

   objFaxDocument.Recipients.Add("01772 123456", "Luke Niland")

   ‘Set the cover page type and the path to the cover page

    objFaxDocument.CoverPageType=
FAXCOMEXLib.FAX_COVERPAGE_TYPE_ENUM.fcptSERVER

   objFaxDocument.CoverPage = "generic.cov"

   ‘Provide the address for the fax receipt

   objFaxDocument.ReceiptAddress = "luke@beakersoft.wanadoo.co.uk"

   ‘Dont attach the original fax to the email receipt

   objFaxDocument.AttachFaxToReceipt = False

   ‘Set the receipt type to email

   objFaxDocument.ReceiptType = FAXCOMEXLib.FAX_RECEIPT_TYPE_ENUM.frtMAIL

 

   ‘Subject into the cover

   objFaxDocument.Subject = "Test Fax"

   ‘Set the sender properties.

   objFaxDocument.Sender.Name = "Luke Niland"

 

   ‘Submit the document to the connected fax server

   objFaxDocument.ConnectedSubmit(objFaxServer)

 

Catch ex As Exception

   Msgbox("Failed Sending Job" & ex.Message & " " & ex.GetBaseException.ToString)

End Try

{mospagebreak title=Explaining the Code}

Okay, the first three lines are our object and the variables we will need. The only object here that we haven’t seen before is the FAXCOMEXLib.FaxDocument. This is the object that is used to create the job and send. The other two lines are the connection to the server as we have seen before, and a variable that will hold the document we are going to fax.

Now we are going to set all the properties of the job, and then send it. All this code is in a TRY/CATCH so we can gracefully handle any errors. First of all we connect to the fax server as we have done before. Then, we set the body of our objFaxDocument object to be the document we want to fax.

You can fax any kind of document you like, as long as the PC running your application has the ability to open the document. In this case we are sending a pdf file, so your PC must have Adobe Reader or something similar installed. 

Now we will set the other properties of the document. There are more available than what we have used here; these are just a guide. First of all set the DocumentName to be whatever you want to call it — here we just name it "Test Fax" — then we set the priority of the job. A higher priority job will get sent before a normal or low one.

Now, we will tell the job where it is going, and who it is going to by adding a recipient to the job. You can add multiple recipients to each job; just use an Add for each one.

After that we set the cover page options. If you don’t want a cover page, you can use FAXCOMEXLib.FAX_COVERPAGE_TYPE_ENUM.fcptNONE. This will just send the document. Here we are telling the job to use a cover page on the server, and then giving it the name of the cover page. You can also use a local cover page if you have one.

Next we set the receipt options. We give it an email address to send the receipt to, tell it not to attach the fax document to the receipt, and set the receipt type to be an email.

We then set the subject of the job, and the sender name. We now have enough details to send the fax, so we use the ConnectedSubmit method of the document and give it to the fax server.

If everything has worked okay, look at your fax server’s outbox, and your job should be in there!

7 thoughts on “More on Controlling Windows Fax Services Using VB.Net

  1. Hi,

    Thanks for this article, I have been trying for several days but I can override this error Operation Failed (0x800710D8) when executing ConnectedSubmit function, but only happens when assigning document.body property, if just sending a cover page it works fine.

    Do you have any idea about it?

    Best regards,
    Silfrido

  2. Hi,That error does’nt ring any bells, but if you can post the chunk of code thats casuing the problems i can have a look

    Cheers
    Luke

  3. Hello,

    We are getting the same error when trying to attach the “Body” to the fax. Was this ever resolved? Any other suggestions as to why this isn’t working?

    Thanks in advance.

  4. Hi, I have never been able to replicate this error. I assume you are getting it when you are just trying to attach some text to the body, not trying to attach a graphic or external file.

    If you post the snippet of code on here you are having a problem with, and what you are trying to make the body of the text i can have a look

  5. When my vbs execute the line ConnectSubmit(FaxServer) each document is opened, any suggestion to avoid that.

    Thanks.

  6. hi,

    i am trying to send multiple faxes automatically, but when i submit “objFaxDocument.ConnectedSubmit(objFaxServer)” the doc to the faxserver a dialog box appear and i need to press the print button manually to send the fax.

    Is there any way i can avoid this screen.

    please need your advice

  7. Thanks for this article, I have used your code in my application, but i am using windows xp fax service. My problem is the faxes are in outbox with pending status only. It will not send to Fax machine. I don’t know where i done a mistake. Pls help me…

[gp-comments width="770" linklove="off" ]