Edit

Share via

TTEmbedFontFromFileA function (t2embapi.h)

  • Article

Creates a font structure containing the subsetted wide-character (16-bit) font. An external file provides the font information.

This function passes the data to a client-defined callback routine for insertion into the document stream.

Syntax

LONG TTEmbedFontFromFileA(
  [in]           HDC            hDC,
  [in]           LPCSTR         szFontFileName,
  [in]           USHORT         usTTCIndex,
  [in]           ULONG          ulFlags,
  [in]           ULONG          ulCharSet,
  [out]          ULONG          *pulPrivStatus,
  [out]          ULONG          *pulStatus,
                 WRITEEMBEDPROC lpfnWriteToStream,
  [in]           LPVOID         lpvWriteStream,
  [in]           USHORT         *pusCharCodeSet,
  [in]           USHORT         usCharCodeCount,
  [in]           USHORT         usLanguage,
  [in, optional] TTEMBEDINFO    *pTTEmbedInfo
);

Parameters

[in] hDC

Device context handle.

[in] szFontFileName

The font file name and path to embed. This is an ANSI string.

[in] usTTCIndex

Zero-based index into the font file (TTC) identifying the physical font to embed. If the file contains a single font (such as a TTF or OTF outline file), this parameter should be set to 0.

[in] ulFlags

Flag specifying the embedding request. This flag can have zero or more of the following values.

Value Meaning
TTEMBED_EMBEDEUDC
 Include the associated EUDC font file data with the font structure.
TTEMBED_RAW
 Return a font structure containing the full character set, non-compressed. This is the default behavior of the function.
TTEMBED_SUBSET
 Return a subsetted font containing only the glyphs indicated by the pusCharCodeSet or pulCharCodeSet parameter. These character codes must be denoted as 16-bit or UCS-4 characters as appropriate for the parameter.
TTEMBED_TTCOMPRESSED
 Return a compressed font structure.

[in] ulCharSet

Flag specifying the character set of the font to be embedded. This flag can have one of the following values.

Value Meaning
CHARSET_UNICODE
 Unicode character set, requiring 16-bit character encoding.
CHARSET_SYMBOL
 Symbol character set, requiring 16-bit character encoding.

[out] pulPrivStatus

Pointer to flag indicating embedding privileges of the font. This flag can have one of the following values. This function returns the least restrictive license granted.

Value Meaning
EMBED_PREVIEWPRINT
 Preview and Print Embedding.
EMBED_EDITABLE
 Editable Embedding.
EMBED_INSTALLABLE
 Installable Embedding.
EMBED_NOEMBEDDING
 Restricted License Embedding.

[out] pulStatus

Pointer to a bitfield containing status information about the embedding request. This field is filled upon completion of this function. No bits are currently defined for this parameter.

lpfnWriteToStream

Pointer to the client-defined callback function that writes the font structure to the document stream. See WRITEEMBEDPROC.

[in] lpvWriteStream

A token to represent the output stream.

[in] pusCharCodeSet

Pointer to the buffer containing the optional Unicode character codes for subsetting. This field is only used for subsetting a font and is ignored if theulFlagsfield does not specify TTEMBED_SUBSET.

[in] usCharCodeCount

The number of characters in the list of characters indicated by pusCharCodeSet. This field is only used for subsetting a font and is ignored if the ulFlags field does not specify TTEMBED_SUBSET.

[in] usLanguage

Specifies which language in the name table to keep when subsetting. Set to 0 to keep all languages. This field is only used for subsetting a font and is ignored if the ulFlags field does not specify TTEMBED_SUBSET.

[in, optional] pTTEmbedInfo

Pointer to a TTEMBEDINFO structure containing the URLs from which the embedded font object may be legitimately referenced. If pTTEmbedInfo is NULL, no URLs will be added to the embedded font object and no URL checking will occur when the client calls the TTLoadEmbeddedFont function.

Return value

If the embedding is successful, returns E_NONE.

The font structure is incorporated into the document stream by the client. pulPrivStatus is set, indicating the embedding privileges of the font; and pulStatus is set to provide results of the embedding operation.

Otherwise, returns an error code described in Embedding-Function Error Messages.

Remarks

This function references a client-defined callback routine for embedding the font structure into the document stream.

Clients are responsible for determining and indicating the character set of the font.

For information on embedding Unicode characters from a device context, see TTEmbedFont; for information on embedding UCS-4 characters from a device context, see TTEmbedFontEx.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header t2embapi.h
Library T2embed.lib
DLL T2embed.dll

See also

TTEMBEDINFO

TTEmbedFont

TTEmbedFontEx

TTLoadEmbeddedFont