Newsletter Archives - March, 2005

Volume 10. Issue 3

[page 1][page 2][page 3] An Inside look at the Fax C++/ActiveX Internal Fax Queue The Fax C++/ActiveX allows developers to send faxes in two unique ways: 1) By sending a fax immediately on an available port or channel or 2) By adding the fax to the internal fax queue.  This intent of this article is to provide a detailed overview of the Fax C++/ActiveX fax queue and its benefits. How it Works: The Fax C++/ActiveX internal fax queue works the same as any queue, the first item added to the queue is the first item out of the queue.  Fax Objects can be added to the queue by the developer’s application, and the queue can accept and store any number of fax objects, and once the fax object has been added to the queue the application can essentially forget about them and let Fax C++/ActiveX manage the fax objects. Fax C++/ActiveX will take the first fax from the queue and will send it on the first available port or channel.  As soon as the next port or channel becomes available, Fax C++/ActiveX will take the next object, and will continue in this manner until the queue has been emptied Variations of the Queue Order The order in which fax objects are added to the queue and subsequently removed form the queue for faxing can be manipulated by changing a given fax object’s priority.  The fax priority functionality was first released in version 11.04 of the Fax C++/ActiveX and allows developers to assign any positive integer value to a fax object.  The higher the priority value, the more important that object is and the further up the queue it moves.  The fax queue will automatically move higher priority faxes up the queue to their correct priority based position. Tracking Objects in the Queue Fax objects in the queue can be tracked in a number of ways, however the most flexible and powerful tracking method is through the use of the User Strings, also released in version 11.04 of the Fax C++/ActiveX.   User strings are a property of each fax object and allow developers to store a string of information along with a particular fax object.  Some possible uses can include storing the faxing users’ name, a tracking number, etc.  Developers can locate objects in the queue by searching for a particular user string and upon locating the string can update some property of the object (fax number, priority, etc.), they can even delete the object entirely if so desired Retrying an Unsuccessful fax Fax C++/ ActiveX internally handles sending faxes on multiple ports by queuing the faxes and sending out the faxes on the first available ports. If the called phone number is busy, a human answer is detected, or some similar error occurs then the fax should be resent after a waiting period. The waiting period ensures or at least makes it more likely that the phone number will not be busy the next time the fax is sent. This retry feature is not directly implemented in Fax C++/ActiveX since the retries will be handled differently by every application, however implementing a retrying mechanism is very simple. Black Ice recently added a new sample to the Fax C++ /ActiveX toolkit which demonstrates how to implement retrying in the case of a busy fax number. The sample will try to resend an unsuccessful fax in three minutes. If sending the fax is unsuccessful again, the sample will retry two more times. The current version of the sample is implemented only for modems, however the retry can be implemented exactly the same way for other fax hardware such as Brooktrout, GammaLink, NMS or Dialogic boards. Sending a Fax The retry sample is implemented for both queued faxes and faxes sent immediately. If “Immediate” mode was used and remote number is busy the sample will try to resend the fax after three minutes. It is important to note that the sample will try to send the fax on the same port as initially selected. If “Queue” was checked and remote number is busy the sample will try to put the fax back into the queue after three minutes. If the remote number is not busy next time, the fax will be sent on the first available port. The sample uses the following logic to implement the retries: 1. The Fax Object is placed in the Fax C++ queue for sending 2. The TERMINATE event is received, the fax number was busy 3. The Fax Object is removed from the Fax C++ queue and it is added to the retry queue of the sample. 4. The timer is started 5. When the previously established time period expires (3 minutes) the Fax Object is removed from the retry queue and it is added to the Fax C++ queue 6. Fax C++ will send the Fax Object on the first available port when the object reaches the top of the fax queue. 7. Steps 2 through 6 are repeated as many times as necessary (number of retries)