The following describes the primary entry points and structures used for graphic importing. Note that the API only accepts ANSI character strings, UNICODE strings not being natively supported.
GetFilterInfo
This function is used to initialize the import filter and to allocate (optional) filter-specific preference memory that is used in subsequent filter calls. It is exported as GetFilterInfo, GetFilterInfo@16, or GETFILTERINFO.
UINT CALLBACK GetFilterInfo(DWORD idVersion, LPSTR lpszIni, HGLOBAL * lphPrefMem, HANDLE * lphFileTypes);IdVersion — expected filter version: 2 for Type 2 filters
lpszIni — unused, set to NULL or ""
lphPrefMem — address of an HGLOBAL variable to receive filter preference settings used in subsequent filter calls. The calling application is responsible for freeing this handle when completed via GlobalFree. Some filters do not support or implement preferences, resulting in *lphPrefMem being set to NULL.
lphFileTypes — unused, set to NULL
Return value:
0 — failed, unable to continue
1 — filter is a text filter
2 — filter is a graphics filter
GetFilterPref
This function allows for the user configuration of various filter-specific preferences. It is an optional entry point: when available it is exported as GetFilterPref, GetFilterPref@16, or GETFILTERPREF. Even though most filters export this function, it is often a stub routine that simply returns without performing any action.
VOID CALLBACK GetFilterPref(HINSTANCE hInstance, HWND hwndParent, HGLOBAL hPrefMem, DWORD dwFlags);hInstance — unused, set to NULL
hwndParent — parent window handle or NULL
hPrefMem — handle to preference memory allocated during call to GetFilterInfo
dwFlags — unused, set to 0
Returns a void.
ImportGR
This function is used to perform the actual graphic import and conversion. It is exported as ImportGR, ImportGr, ImportGR@16, ImportGr@16, or IMPORTGR. Note that some filters will display a progress dialog during the import and conversion process.
UINT CALLBACK ImportGR(HDC hdcPrint, FILESPEC * lpfs, PICTINFO * lppi, HGLOBAL hPrefMem);hdcPrint — template device context used during importing and conversion, or NULL to use default conversion characteristics
lpfs — address of a FILESPEC structure that defines the file to be imported
lppi — address of a PICTINFO structure. On success, this is populated with the import results.
HPrefMem — handle to preference memory allocated during call to GetFilterInfo
Listing 1 documents the error codes returned by function ImportGR.
FILESPEC
This structure is used to define the input file. The fullName field is used to define the path and file name of the source graphic file. Not all filters properly handle long file names; therefore it is recommended that the short form of a file name be used where possible [7]. The meaning and use of the other fields is unknown in 32-bit filters and should be set to zero.
typedef DWORD FILETYPE; typedef struct { WORD slippery : 1; WORD write : 1; WORD unnamed : 1; WORD linked : 1; WORD mark : 1; FILETYPE fType; WORD handle; char fullName[MAX_PATH]; DWORD filePos; } FILESPEC;PICTINFO
The PICTINFO structure is used to store the results of the import process. The hmf field defines the imported graphic as a standard Windows metafile, the bbox field describes the bounding rectangle in metafile units, and the inch field contains the metafile units per inch. Note that the hmf handle may be either a Windows metafile handle (HMETAFILE) or a global handle (HGLOBAL) to an in-memory image of a metafile. Such global handle based metafiles must either be converted to a standard or enhanced metafile, or displayed manually. (Using PlayMetaFile on a global handle will fail with a last error of ERROR_INVALID_HANDLE.)
typedef struct { HANDLE hmf; RECT bbox; DWORD inch; } PICTINFO;