Work with Fax [Using FAXCOMEXLib]

Introduction

In this article i'm talking about how to be aware when a fax recieve and take the fax, in this article we are using FAXCOMEXLib and we won't go through advance stuff as i'm unaware of many things, but as i needed to know this much and nobody shared any thing about it, i though it gonna be useful for Beginners. I also like to here your idea to make the article work better and more internally.
[NOTE: THAT WE ONLY TALKED ABOUT HOW TO RECEIVE FAX IN THIS ARTICLE FOR NOW]

Background

It was sometimes ago, my manager asked me for ability to receive fax, and i was wonder, what fax? so i start searching, i find nothing much, just several paid library, and a Fax4J library, first i though of converting the lib for .Net but it was failur as it only provided sending features. so, i just follow something about FAXCOMLib and i find several different question answers. they all were alike, and the source was MSDN, but it was disappointing at it didn't had that much of information. BTW, i follow those things and rich nowhere far but here. and i'm goin' to share this.

Where to find the Library

First thing you gonna need to work with this library is the library itself. so you do need to provide it somehow. for that you need to install one of windows feature that is named "Fax Server Tools", in non server windows it may have a different name.

After installing this feature, you can search for the dll inside your VS, So go to References Node of your solution explorer, and then right click on it, and choose "Add Reference...", next move to COM section. and choose the "faxcom 1.0 Type Library".

Now you have the reference you need.

Using the code

Well as you are done most of the things you should do, i'm wonder how i should talk about the code in here, on a way that you don't say "This is it?"

So here we start...

First you need to import the "FAXCOMEXLib" namespace.

Then you gonna need to create an instance of the FaxServerClass too.
The FaxServerClass is a class that communicate with the windows Fax Service. and receive fax events. Since You may be over a network and your fax server be on a different machine, you need to tell the class which machine it need to connect to. so You give it a computer name, which you can find your on on the propertise of your computer, can be found by right clicking over MyComputer, or ThisPC on windows server, and choose "Propertiese".

Now, you have both the class instance and the name of the computer who running the Fax Service on. the only this is left to perform the first step, is to connect to that PC, so you will call the Connect Method.

So it gonna be something like this:

public class Fax
{
    private readonly FaxServerClass faxSrv;
    public Fax()
    {
        faxSrv = new FaxServerClass();

        var serverName = "WIN-0640S5M4APO";

        faxSrv.Connect(serverName);
        ...
    }
}

Now you are connected to the service, but what now? you need to be notified and even then you need to do your own stuffs. So you need to define and register for the events.

public Fax()
{
    ...
    faxSrv.OnOutgoingJobChanged += faxSrv_OnOutgoingJobChanged;
    faxSrv.OnOutgoingJobAdded += faxSrv_OnOutgoingJobAdded;
    faxSrv.OnOutgoingJobRemoved += faxSrv_OnOutgoingJobRemoved;

    faxSrv.OnIncomingJobAdded += faxSrv_OnIncomingJobAdded;
    faxSrv.OnIncomingJobChanged += faxSrv_OnIncomingJobChanged;
    faxSrv.OnIncomingJobRemoved += faxSrv_OnIncomingJobRemoved;
}
    
private void faxSrv_OnIncomingJobRemoved(FaxServer pfaxserver, string bstrjobid)
{
    //Your Codes
}

private void faxSrv_OnIncomingJobChanged(FaxServer pfaxserver, string bstrjobid, FaxJobStatus pjobstatus)
{
    //Your Codes
}

private void faxSrv_OnIncomingJobAdded(FaxServer pfaxserver, string bstrjobid)
{
    //Your Codes
}

private void faxSrv_OnOutgoingJobRemoved(FaxServer pfaxserver, string bstrjobid)
{
    //Your Codes
}

private void faxSrv_OnOutgoingJobAdded(FaxServer pfaxserver, string bstrjobid)
{
    //Your Codes
}

private void faxSrv_OnOutgoingJobChanged(FaxServer pfaxserver, string bstrjobid, FaxJobStatus pjobstatus)
{
    //Your Codes
}

As you have seen a lot of times, this is how we register for event <instance>.<event> += <Your method>;, and you implement your method, after that, every time an event occure it will go through your code and do what you need to be done, but in this library, it alone won't do any thing... you need to filter the events you need, and tell the machin which events to filter, the following are some of important filter we goona need.

/* This one activates:
   - OnOutgoingJobChanged
   - OnOutgoingJobAdded
   - OnOutgoingJobRemoved*/
FAXCOMEXLib.FAX_SERVER_EVENTS_TYPE_ENUM.fsetOUT_QUEUE 

/* And this one activates:
   - OnIncomingJobChanged
   - OnIncomingJobAdded
   - OnIncomingJobRemoved*/
FAXCOMEXLib.FAX_SERVER_EVENTS_TYPE_ENUM.fsetIN_QUEUE 

So we need to tell the class to filter these event for us, and listen to them, here's how we do this:

public Fax()
{
    ...
    faxSrv.ListenToServerEvents(FAXCOMEXLib.FAX_SERVER_EVENTS_TYPE_ENUM.fsetOUT_QUEUE |
                                FAXCOMEXLib.FAX_SERVER_EVENTS_TYPE_ENUM.fsetIN_QUEUE);
}

With this one line, your class start to work, and as we right these all on constructor, it just begin it's work once you new it. but, before these events trigger we need to answer the calls, so you need to tell your Fax Service to do this for you. search for Fax Service Manager on your server, it may have different names on different OS, or may only be exist on a server machins, i'm not sure of this.

Well after you run this application, you need to find your modem node, the one is connected to the line, and then tell him to answer calls automatically.

And now every thing is ready, you can put some break points inside your methods, and catch the event that occure...

I my self used the OnIncomingJobRemoved to be notified after receiving a fax, and do some operation on the resulting data... here's what i do:

private void faxSrv_OnIncomingJobRemoved(FaxServer pfaxserver, string bstrjobid)
{
    Console.WriteLine("IN - Job ID: " + bstrjobid + " Job Removed from Fax Queue");
    var baseDir = pfaxserver.Configuration.ArchiveLocation;
    var inbox = baseDir + "\\Inbox";
    string[] files = Directory.GetFiles(inbox);

    //Method That search for current file inside the file list...
    Func<string[], string, string> getFilePath =
        (fileList, searchId) => (
            from file in fileList
            let fileName = Path.GetFileNameWithoutExtension(file)
            let dollarIndex = fileName.IndexOf('$')
            where dollarIndex != -1
            where Path.GetFileNameWithoutExtension(file)?.Substring(dollarIndex + 1) == searchId
            select file
            ).FirstOrDefault();

    string filePath = getFilePath(files, bstrjobid);
}

In the last line of code you have the file that is received, which also is kept inside archive folder of the place that has been set for the fax service, you can process it... .

Be aware that i used some of C# 5 or 6 feature in here. like x?.y() mean if(x!=null) x.y()

Thank you for reading,
And if you know something, please tell my to let people have better exprience using this library.