GpiQueryFontFileDescriptions

This function determines whether a given file is a font resource file, and if so, returns the family and face names of the fonts that it contains.

Syntax

GpiQueryFontFileDescriptions(hab, pszFilename, plCount, affdescsNames)

Parameters

hab (HAB) - input

Anchor-block handle.

pszFilename (PSZ) - input

Fully qualified filename.

This is the name of the font resource. The filename extension is .FON.

plCount (PLONG) - in/out

Pointer to the maximum number of family and face name pairs to be returned.

A pointer to the number of pairs of descriptions that are actually returned in affdescsNames is returned in this variable.

affdescsNames (PFFDESCS) - output

Array of font file descriptors.

An array of 2*plCount consecutive 32-byte fields, in which the family and face names of each font, in turn, are returned alternately. :For each pair, the family name is returned first.

Returns

lRemFonts (LONG) - returns

Returns.

>=0

Number of fonts for which details were not returned.

GPI_ALTERROR

Error.

Errors

Possible returns from WinGetLastError

PMERR_INV_FONT_FILE_DATA (0x2073)

The font file specified with GpiLoadFonts, GpiLoadPublicFonts, GpiQueryFontFileDescriptions, or GpiQueryFullFontFileDescs contains invalid data.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

Remarks

Details are returned for as many fonts as can be held in affdescsNames.

By inspecting the returned data, the application can tell whether a particular font resource file contains the fonts it requires, before loading it.

By specifying plCount as a pointer to 0, and then looking at the value returned by the font an application can determine how many fonts there are in the file, and then allocate the correct amount of buffer space for a subsequent call to obtain all of the names.

Example Code

#define INCL_GPILCIDS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HAB         hab;            /*  Anchor-block handle. */
PSZ         pszFilename;    /*  Fully qualified filename. */
PLONG       plCount;        /*  Pointer to the maximum number of family and face name pairs to be returned. */
PFFDESCS    affdescsNames;  /*  Array of font file descriptors. */
LONG        lRemFonts;      /*  Returns. */

lRemFonts = GpiQueryFontFileDescriptions(
             hab, pszFilename, plCount, affdescsNames);

This example uses the GpiQueryFontFileDescriptions to retrieve the typeface family and names for the fonts in the HELV.FON file. The function is called twice, once to determine the actual number of fonts in the file, and again to retrieve the descriptions.

#define INCL_GPILCIDS           /* Font functions               */
#define INCL_DOSMEMMGR          /* DOS Memory Manager Functions */
#include <os2.h>

HAB hab;                /* anchor-block handle                  */
PFFDESCS pffdescs;      /* array of font file descriptors       */
LONG cFonts = 0;        /* number of descriptions not returned  */

/* Retrieve a count of all fonts in the file. */

cFonts = GpiQueryFontFileDescriptions(hab, "C:\\HELV.FON", &cFonts,
                                      NULL);

/* Allocate space for the descriptions. */

ret = DosAllocMem((PPVOID *)&pffdescs,(ULONG)(cFonts*sizeof(FFDESCS)),
            PAG_COMMIT | PAG_READ | PAG_WRITE);
if (ret != 0) {
        DosBeep(100,100);
        err = WinGetLastError(hab);
        DosFreeMem(pffdescs);
        exit(-1);
}
/* Retrieve the descriptions. */

GpiQueryFontFileDescriptions(hab, "C:\\OS2\\DLL\\HELV.FON", &cFonts,
                             pffdescs);