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

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.

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

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);