GpiQueryFullFontFileDescs

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

GpiQueryFullFontFileDescs(hab, pszFilename, plCount, pNames, plNamesBuffLength)

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: Maximum number of family and face name pairs to be returned.; The number of pairs of descriptions that are actually returned in pNames is returned in this variable.

pNames (PVOID) - output: Font file descriptors.; A buffer in which the font file family and face name pairs are returned. They are each returned in a FFDESCS2 structure, with successive structures packed end to end.

plNamesBuffLength (PLONG) - in/out: Length, in bytes, of the pNames data buffer.; On return, this is set to the actual length needed to hold all of the family names and face names in the file.

Return Value

lRemFonts (LONG) - returns

Returns.

>=0: Number of fonts for which details were not returned
GPI_ALTERROR: Error.

Remarks

Details are returned for as many fonts as can be held in pNames. 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 pNames as NULL, and then looking at the value returned in plNamesBuffLength, an application can determine the length of the buffer needed to hold all of the font names. Support for this function is device dependent.

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.

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;            /* Maximum number of family and face name pairs to be returned. */
PVOID pNames;             /* Font file descriptors. */
PLONG plNamesBuffLength;  /* Length, in bytes, of the data buffer. */
LONG  lRemFonts;          /* Returns. */

lRemFonts = GpiQueryFullFontFileDescs(hab, pszFilename, plCount, pNames, plNamesBuffLength);

This example uses the GpiQueryFullFontFileDescs 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.

HAB hab;
PFFDESCS pffdescs;
LONG cFonts = 0;
LONG lBuflen = 0;

/* Retrieve a count of all fonts in the file. */
cFonts = GpiQueryFontFileDescriptions(hab, "C:\\HELV.FON", &cFonts, NULL, &lBuflen);

/* Allocate space for the descriptions. */
DosAllocMem((VOID *)pffdescs,(ULONG)(cFonts*sizeof(FFDESCS)), PAG_COMMIT | PAG_READ | PAG_WRITE);

/* Retrieve the descriptions. */
GpiQueryFullFontFileDescs(hab, "C:\\HELV.FON", &cFonts, pffdescs, &lBuflen);