Font Path Elements

At the center of the general font access methods used by X and xfs is the Font Path Element data structure. Like most structures in the X server, this contains a collection of data and some function pointers for manipulating this data:

/* External view of font paths */
typedef struct _FontPathElement {
    int         name_length;
    char       *name;
    int         type;
    int         refcount;
    pointer     private;
} FontPathElementRec, *FontPathElementPtr;

typedef struct _FPEFunctions {
    int         (*name_check) ( /* name */ );
    int         (*init_fpe) ( /* fpe */ );
    int         (*reset_fpe) ( /* fpe */ );
    int         (*free_fpe) ( /* fpe */ );
    int         (*open_font) (  /* client, fpe, flags,
                        name, namelen, format,
                        fid,  ppfont, alias */ );
    int         (*close_font) ( /* pfont */ );
    int         (*list_fonts) ( /* client, fpe, pattern,
                        patlen, maxnames, paths */ );
    int         (*start_list_fonts_with_info) (
                        /* client, fpe, name, namelen,
                           maxnames, data */ );
    int         (*list_next_font_with_info) (
                        /* client, fpe, name, namelen,
                           info, num, data */ );
    int         (*wakeup_fpe) ( /* fpe, mask */ );
    int         (*client_died) ( /* client, fpe */ );
} FPEFunctionsRec, FPEFunctions;

/* External view of font paths */
typedef struct _FontPathElement {
    int         name_length;
    char       *name;
    int         type;
    int         refcount;
    pointer     private;
} FontPathElementRec, *FontPathElementPtr;

typedef struct _FPEFunctions {
    int         (*name_check) ( /* name */ );
    int         (*init_fpe) ( /* fpe */ );
    int         (*reset_fpe) ( /* fpe */ );
    int         (*free_fpe) ( /* fpe */ );
    int         (*open_font) (  /* client, fpe, flags,
                        name, namelen, format,
                        fid,  ppfont, alias */ );
    int         (*close_font) ( /* pfont */ );
    int         (*list_fonts) ( /* client, fpe, pattern,
                        patlen, maxnames, paths */ );
    int         (*start_list_fonts_with_info) (
                        /* client, fpe, name, namelen,
                           maxnames, data */ );
    int         (*list_next_font_with_info) (
                        /* client, fpe, name, namelen,
                           info, num, data */ );
    int         (*wakeup_fpe) ( /* fpe, mask */ );
    int         (*client_died) ( /* client, fpe */ );
} FPEFunctionsRec, FPEFunctions;

The function pointers are split out from the data structure to save memory; additionally, this avoids any complications when initializing the data structure as there would not be any way to discover the appropriate function to call (a chicken and egg problem).

When a font path type is initialized, it passes the function pointers to the server which are then stored in an FPEFunctionsRec. Each function is described below in turn.

(*name_check)

Each new font path member is passed to this function; if the return value is Successful, then the FPE recognises the format of the string. This does not guarantee that the FPE will be able to successfully use this member. For example, the disk-based font directory file fonts.dir may be corrupted, this will not be detected until the font path is initialized. This routine never returns Suspended.

(*init_fpe)

Initialize a new font path element. This function prepares a new font path element for other requests: the disk font routine reads the fonts.dir and fonts.alias files into the internal format, while the font server routine connects to the requested font server and prepares for using it. This routine returns Successful if everything went OK, otherwise the return value indicates the source of the problem. This routine never returns Suspended.

(*reset_fpe)

When the X font path is reset, and some of the new members are also in the old font path, this function is called to reinitialize those FPEs. This routine returns Successful if everything went OK. It returns FPEResetFailed if (for some reason) the reset failed, and the caller should remove the old FPE and simply create a new one in its place. This is used by the disk-based fonts routine as resetting the internal directory structures would be more complicated than simply having destroying the old and creating a new.

(*free_fpe)

When the server is finished with an FPE, this function is called to dispose of any internal state. It should return Successful, unless something terrible happens.

(*open_font)

This routine requests that a font be opened. The client argument is used by the font library only in connection with suspending/restarting the request. The flags argument specifies some behaviour for the library and can be any of:

/* OpenFont flags */
#define FontLoadInfo    0x0001
#define FontLoadProps   0x0002
#define FontLoadMetrics 0x0004
#define FontLoadBitmaps 0x0008
#define FontLoadAll     0x000f
#define FontOpenSync    0x0010

/* OpenFont flags */
#define FontLoadInfo    0x0001
#define FontLoadProps   0x0002
#define FontLoadMetrics 0x0004
#define FontLoadBitmaps 0x0008
#define FontLoadAll     0x000f
#define FontOpenSync    0x0010

The various fields specify which portions of the font should be loaded at this time. When FontOpenSync is specified, this routine will not return until all of the requested portions are loaded. Otherwise, this routine may return Suspended. When the presented font name is actually an alias for some other font name, FontNameAlias is returned, and the actual font name is stored in the location pointed to by the alias argument as a null-terminated string.

(*close_font)

When the server is finished with a font, this routine disposes of any internal state and frees the font data structure.

(*list_fonts)

The paths argument is a data structure which will be filled with all of the font names from this directory which match the specified pattern. At most maxnames will be added. This routine may return Suspended.

(*start_list_fonts_with_info)

This routine sets any internal state for a verbose listing of all fonts matching the specified pattern. This routine may return Suspended.

(*list_next_font_with_info)

To avoid storing huge amounts of data, the interface for ListFontsWithInfo allows the server to get one reply at a time and forward that to the client. When the font name returned is actually an alias for some other font, FontNameAlias will be returned. The actual font name is return instead, and the font alias which matched the pattern is returned in the location pointed to by data as a null-terminated string. The caller can then get the information by recursively listing that font name with a maxnames of 1. When Successful is returned, the matching font name is returned, and a FontInfoPtr is stored in the location pointed to by data. Data must be initialized with a pointer to a FontInfoRec allocated by the caller. When the pointer pointed to by data is not left pointing at that storage, the caller mustn't free the associated property data. This routine may return Suspended.

(*wakeup_fpe)

Whenever an FPE function has returned Suspended, this routine is called whenever the application wakes up from waiting for input (from select(2)). This mask argument should be the value returned from select(2).

(*client_died)

When an FPE function has returned Suspended and the associated client is being destroyed, this function allows the font library to dispose of any state associated with that client.