Reads an embedded font from the document stream and installs it. Also allows a client to further restrict embedding privileges of the font.
LONG TTLoadEmbeddedFont( _Out_ HANDLE *phFontReference, _In_ ULONG ulFlags, _Out_ ULONG *pulPrivStatus, _In_ ULONG ulPrivs, _Out_ ULONG *pulStatus, _In_ READEMBEDPROC lpfnReadFromStream, _In_ LPVOID lpvReadStream, _In_opt_ LPWSTR szWinFamilyName, _In_opt_ LPSTR szMacFamilyName, _In_opt_ TTLOADINFO *pTTLoadInfo );
- phFontReference [out]
A pointer to a handle that identifies the installed embedded font. This handle references an internal structure, not an Hfont.
- ulFlags [in]
A flag specifying loading and installation options. Currently, this flag can be set to zero or the following value:
Load the font so that it is not enumerated to the user. If the font is not installable, it will remain private.
- pulPrivStatus [out]
A pointer to flag indicating embedding privileges of the font. This flag is written upon completion of this function and can have one of the following values. This function returns the least restrictive license granted.
- ulPrivs [in]
A flag indicating a further restriction of embedding privileges, imposed by the client loading the font. This flag must have one of the following values.
Preview and Print Embedding.
Restricted License Embedding.
Use default embedding level.
- pulStatus [out]
A pointer to a bitfield containing status information about the TTLoadEmbeddedFont request. This field is filled upon completion of this function and can have zero or more of the following values.
The font loaded is a subset of the original font.
The font loaded was labeled as installable and has been added to the registry so it will be available upon startup.
- lpfnReadFromStream [in]
A pointer to the client-defined callback function that reads the font structure from the document stream.
- lpvReadStream [in]
A pointer to the stream (font structure).
- szWinFamilyName [in, optional]
A pointer to the new 16-bit-character Unicode Microsoft Windows family name of the font. Set to NULL to use existing name. When changing the name of a font upon loading, you must supply both this parameter and the szMacFamilyName parameter.
- szMacFamilyName [in, optional]
A pointer to the new 8-bit-character Macintosh family name of the font. Set to NULL to use existing name. When changing the name of a font upon loading, you must supply both this parameter and the szWinFamilyName parameter.
- pTTLoadInfo [in, optional]
A pointer to a TTLOADINFO structure containing the URL from which the embedded font object has been obtained. If this value does not match one of those contained in the TTEMBEDINFO structure, the font will not load successfully.
If successful, returns E_NONE.
If font loading is successful, a font indicated by phFontReference is created from the font structure with the names referenced in szWinFamilyName and szMacFamilyName. pulPrivStatus is set indicating the embedding privileges of the font; and pulStatus may be set indicating status information about the font loading operation.
Otherwise, returns an error code described in Embedding Function Error Messages.
To assist a client in determining whether an embedded font is already installed on the system, the font loading function will return an error message indicating a font with the same name exists on the system (E_FONTNAMEALREADYEXISTS), and if that font has the same checksum as the embedded font (E_FONTALREADYEXISTS). The client then has two options:
- Assume that the installed font is really the same as the embedded font and covers the same subsets.
- Force the embedded font to be installed with a different name to avoid incompatibilities with the font already on the system.
To change the name of an embedded font prior to installing, the client must supply both the 8-bit-character and 16-bit-character name strings as parameters. The font name will be changed in the name table of the newly installed font. The new name is only available to the client and will not be enumerated to the user.
To use the existing name of the embedded font, the name string parameters need to be set to NULL.
Minimum supported client
|Windows 2000 Professional [desktop apps only]|
Minimum supported server
|Windows 2000 Server [desktop apps only]|