6.6. Using Windows Font Handles

• 6.6.1. VFX and DSP-Based Group 3 Fax Font Features
• 6.6.2. Using fx_setparm( ) and fx_getparm( ) to Select Fonts
• 6.6.3. Overriding Fonts Set with fx_setparm( )
• Specify a Font in DF_ASCIIDATA
• Use Control Characters in ASCII Document Prior to Sending
• 6.6.4. Compatibility Issues
• All VFX Products
• VFX/40ESCplus
• VFX/40, VFX/40E, VFX/40SC and VFX/40ESC
• 6.6.5. Preserving Dialogic Fonts as Default Fonts
• Location of Dialogic Fonts
• Steps to Enable Dialogic Fonts
• Example

DSP Fax uses Windows font handles in ASCII to fax conversion. This method differs from the methods used in VFX products as described in Section 6.6.4. Compatibility Issues. By using Windows font handles, you can choose from the entire selection of fonts available in Windows or you can supply your own font resources. For details on how to create font handles and font resources, see your Software Development Kit documentation.

With DSP Fax, the conversion of ASCII text to fax format is performed on the host CPU rather than on Dialogic fax boards.

6.6.1. VFX and DSP-Based Group 3 Fax Font Features

The following table compares the font features on VFX products and DSP Fax.

Table 15. Comparison of VFX and DSP Fax Font Features

VFX Products	DSP-Based Group 3 Fax
Two fonts available system-wide	Two fonts available per channel, reset to the default for each fx_open( )
Two fonts active for each fx_sendfax( )	Two fonts active for each fx_sendfax( )
Choice of language character sets: English and Japanese Katakana	No limitation on language or character set
Choice of two point sizes	No limitation on point sizes

6.6.2. Using fx_setparm( ) and fx_getparm( ) to Select Fonts

Use the following parameter IDs with fx_setparm( ) and fx_getparm( ) to select or return fonts: FC_FONT0 and FC_FONT3.

The parameter IDs are defined as follows:

• FC_FONT0 -- defaults to OEM_FIXED_FONT 12-point. The font specified by FC_FONT0 is applied by default to the fax document.
• FC_FONT3 -- defaults to OEM_FIXED_FONT 9-point. FC_FONT3 defines a second font to be available for use. It also sets the font for the header.

If you use DSP Fax out of the box, your ASCII to fax document (without any special control characters within the document itself) is rendered in a default 12-point font similar to the Windows standard OEM_FIXED_FONT. Headers are rendered in a default 9-point font.

You can select two fonts for each fax channel device by specifying font handles using fx_setparm( ) and FC_FONT0 and FC_FONT3 as parameter IDs.

Each parameter ID initializes a font handle to make the specified font available for use in rendering an ASCII document. Two font handles can be active at one time on a fax channel device; they are stored in the fax library. The font handle must remain open for the duration of the fax transmission; that is, the font handle must not be deleted until the fax transmission has completed. You must delete the handle when it is no longer needed.

You can replace the default values with any other Windows font or your own font resource. For details on how to create font handles and font resources, see your Software Development Kit documentation.

To override the default font or specify the use of a different font, see Section 6.6.3. Overriding Fonts Set with fx_setparm( ) on page 94 for more information.

If you don't specify FC_FONT0 or FC_FONT3, your ASCII document will use the default font previously available.

For more information on fx_getparm( ) and fx_setparm( ), see Chapter 9. Fax Library Function Reference.

6.6.3. Overriding Fonts Set with fx_setparm( )

As described in Section 6.6.2. Using fx_setparm( ) and fx_getparm( ) to Select Fonts, fonts used in ASCII to fax conversion are selected for each fax device channel using fx_setparm( ). The following methods override the default font specified in fx_setparm( ). These methods are optional and are described in order of precedence.

• using the font field of the DF_ASCIIDATA data structure
• using control characters in the ASCII document prior to sending

Specify a Font in DF_ASCIIDATA

The font field in the DF_ASCIIDATA data structure specifies the font in use for a specific ASCII document associated with a specific DF_IOTT structure. Valid values are DF_FONT_0 and DF_FONT_3.

This font overrides FC_FONT0 and becomes the default font for the current fax transmission. The subsequent fax transmission reverts to using the font specified in FC_FONT0 as the default font.

For example, if you want a specific ASCII document (associated with a specific DF_IOTT structure) to use FC_FONT3 as the default font, then specify DF_FONT_3 as the value in the font field.

For further information on DF_ASCIIDATA, see Section 7.3. DF_ASCIIDATA -- ASCII Data Description on page 101.

Use Control Characters in ASCII Document Prior to Sending

To apply a second font in your fax document in addition to the default font, you must edit your ASCII document and insert the proper control characters before the line on which the change will take place. The new format takes effect on the next full line of text. These control characters override the font set in the DF_ASCIIDATA data structure. This method may be useful when applying a font to specific parts of your document (such as headings) rather than to the entire document.

For example, if you want to use the font specified by FC_FONT3, insert <ESC>F3 or ~F3 in your ASCII document before the line on which the change will take place. The new format takes effect on the next full line of text. To return to the default font, insert <ESC>F0 or ~F0.

For further information on control characters, see the ASCII to Fax tables in Appendix F.

6.6.4. Compatibility Issues

DSP Fax uses Windows font handles for ASCII to fax conversion. This method differs from the methods used in previous hardware platforms from Dialogic. If you developed fax applications on a VFX product, you will have to modify your applications to reflect this change.

Note the following compatibility issues.

All VFX Products

Unlike VFX products, DSP Fax uses Windows fonts as default fonts in ASCII to fax conversion rather than Dialogic's proprietary fonts (see ASCII to Fax tables in Appendix F).

For more information on how to enable Dialogic fonts as default fonts in ASCII to fax conversion in DSP Fax, see Section 6.6.5. Preserving Dialogic Fonts as Default Fonts on page 96.

VFX/40ESCplus

If you developed applications on VFX/40ESCplus boards, note that the following utility and function call are not supported in DSP Fax:

• ASCII Font Loader demonstration utility, which is used to load fonts on the VFX/40ESCplus, is not supported in DSP Fax.
• fx_loadfont( ) function, which is an alternate method used to load fonts on the VFX/40ESCplus, is not supported in DSP Fax. This function will return the error EFX_UNSUPPORTED.

VFX/40, VFX/40E, VFX/40SC and VFX/40ESC

If you developed applications on VFX/40, VFX/40E, VFX/40SC or VFX/40ESC boards, the configuration file (.cfg) used to load fonts is not supported in DSP Fax.

6.6.5. Preserving Dialogic Fonts as Default Fonts

In VFX products, ASCII to fax conversion is performed in the firmware and ASCII documents are rendered using Dialogic's proprietary fonts (see ASCII to Fax tables in Appendix F).

The use of Windows font handles in DSP Fax enables you to specify any Windows font or to supply your own font resources. The default fonts provided by DSP Fax are Windows fonts.

You can enable Dialogic fonts as default fonts in ASCII to fax conversion in DSP Fax by following the directions in this section.

Location of Dialogic Fonts

Dialogic font files are provided with the Dialogic System Software and SDK and installed by default in the ...\dialogic\fonts subdirectory. To enable applications to use Dialogic fonts, application developers must package and re-distribute these font files with their applications.

Steps to Enable Dialogic Fonts

To use Dialogic fonts for rendering ASCII to fax documents, modify your application as follows:

1. Call the Win32 API AddFontResource(font_filename) to notify the operating system of the presence of new fonts, namely, the Dialogic fonts. You will also need to notify other applications of the new fonts. For more information, see your Software Development Kit documentation.
2. Establish an LFONT structure with the appropriate parameter to prepare for the creation of a new font.
3. Call the Win32 API CreateFontIndirect( ) to obtain a font handle.
4. Use the Dialogic fx_setparm( ) function call to store this font handle in the Dialogic fax library.
5. Call the Win32 API RemoveFontResource( ) to remove the font. You will also need to notify other applications of the removal.

For more information on the Win32 API, see the Microsoft Win32 API Programmer's Reference.

Example

The following example shows one way to specify the use of Dialogic fonts (Japanese Katakana character set) in rendering ASCII to fax documents.

To see an example of how to specify the use of a Windows font, see the example for fx_setparm( ) and FC_FONT0 on page 303.

// ...  
// open device using fx_open( )  
// ...  
// The next line of code is required when your application needs to use old  
// Dialogic fonts.  
// It specifies the font-resource filename. Assume in same directory as  
// application.  
LOGFONT lFont;  
HFONT hFont;  
ret = AddFontResource("katakna0.fon");  
memset(&lFont, 0, sizeof(lFont));  
lFont.lfCharSet = OEM_CHARSET;  
strcpy(lFont.lfFaceName, "Katakna0");  
hFont = CreateFontIndirect(&lFont);  
if ((fx_setparm ( dev, FC_FONT_0, (void *)&hFont)) == -1)  
{  
printf("LastError: %d, ErrorMsg = %s\n", ATDV_LASTERR ( dev ),  
         ATDV_ERRMSGP( dev ));  
         fx_close ( dev );  
         exit ( 0 );  
}

Click here to contact Dialogic Customer Engineering