# TPVAPIOpenDocumentInfo

This structure defines the parameters used by the VAPIMWP_INIT_OPEN_DOCUMENT message to open a document.

## Syntax

    #include <kvvapi.h>
    typedef struct tag_TPVAPIOpenDocumentInfo
    {
        int                size;
        LPSTR              lpszFilePath;
        KPTPIOobj*         lpIOobj;
        adDocDesc*         lpadDocDesc;
        BOOL               bADInstallViewer;
        int                nViewAsMode;
        LPSTR              lpszOrigFilePath;
        Int                nFlags;
        LPSTR              lpszResID;
        LPSTR              lpszVMLFilePath;
        Void*              lpOptions;
        HGLOBAL            hGlobalMem;
        DWORD              dwcbGlobalMem;
        BOOL               bWait;
        int                nGeneralTab;
        BOOL               bAutoViewAsText;
        LPSTR              lpszHighLight;
        BOOL               bMatchHighLightCase;
    }
    TPVAPIOpenDocumentInfo;

## Members

`size` | This parameter must be initialized to `sizeof(TPVAPIOpenDocumentInfo)` before calling `VAPIMWP_INIT_OPEN_DOCUMENT`.
`lpszFilePath` | A string containing the full file path of the document to open. This is not required if you are using `lpIOobj` or `hGlobalMem`.
`lpIOobj` | A pointer to a KPTPIOobj structure that contains the I/O object of the document to open. This is not required if you are using `lpszFilePath` or `hGlobalMem`.
`lpadDocDesc` | A pointer to an `adDocDesc` structure that contains the document format information. Set this to `NULL`.
`bADInstallViewer` | A flag to install Viewer if the document is not supported (optional).
`nViewAsMode` | A flag to display the document as formatted text, text, or hexadecimal (optional). The options are described in Options for nViewAsMode .
`lpszOrigFilePath` | If `lpszFilePath` is not the original file path, this optional string contains the full path to the original file.
`nFlags` | A bit field that contains additional options for opening a document (optional). The options are described in Options for nFlags .
`lpszResID` | A string that contains the resource ID to use (optional).
`lpszVMLFilePath` | Reserved. Set this to `NULL`.
`lpOptions` | A pointer to an ALL_OPTIONS_EX structure to change the default options for the document (optional). See Change Document Options for more information.
`hGlobalMem` | A block of memory that contains the input file data (optional). If you use this member, `lpIOobj` and `lpszFilePath` must be `NULL`.
`dwcbGlobalMem` | The size in bytes of the memory specified by `hGlobalMem`. This is ignored if `hGlobalMem` is not used.
`bWait` | Set to `TRUE` to make `SendMessage()` on open not return until the document is fully processed. This ensures that the document is fully processed before an operation (such as printing, converting, or searching) is performed, and is useful when you want to use an operation immediately after opening the document. If you are opening a document for viewing only, set this to `FALSE` so that the first page of the document can be viewed as soon as it is processed. If you are drawing a word processing document and only want to process it up to the specified page, set `bWait` to `FALSE`. When the specified page is reached, processing is paused. This setting minimizes delays.
`nGeneralTab` | This parameter must be set to `0`.
`bAutoViewAsText` | If you set this flag to `TRUE`, the document is automatically displayed as unformatted text when the document format cannot be determined or is not supported (optional). This member will be deprecated in a future release. To display an unknown or unsupported format as text or hexadecimal, set nViewAsMode to `VIEW_MODE_AUTO_TEXT` or `VIEW_MODE_AUTO_HEX`.
`lpszHighLight` | A string that contains text to be highlighted if it is found in the document (optional). You can either search for an intact string or for individual words that might or might not be adjacent. To search for individual words, separate each word with `\t`, which indicates a tab.
`bMatchHighLightCase` | A flag to indicate if the text in `lpszHighLight` is to be matched case-sensitively (`TRUE` if it is case sensitive).

## Discussion

- If the `bWait` parameter is set to `TRUE`, you can determine whether the document has been completely processed and is ready for an operation by using the appropriate "`Can`" messages, such as `VAPIMWP_CANCONVERT`, `VAPIMWP_FILE_CANSAVEAS`, and `VAPIMWP_PRINT_CANPRINT`.

- The `nViewAsMode` member can be one of the following options:

Options for nViewAsMode
Option | Description
--- | ---
`VIEW_MODE_NORMAL` | Displays the document as formatted text when the format can be determined and is supported. This is the default.
`VIEW_MODE_TEXT` | Displays each byte as ASCII when the format can be determined.
`VIEW_MODE_HEX` | Displays each byte as hexadecimal when the format can be determined.
`VIEW_MODE_AUTO_TEXT` | Automatically displays each byte as ASCII when the format cannot be determined or is not supported. This option overrides the setting in bAutoViewAsText.
`VIEW_MODE_AUTO_HEX` | Automatically displays each byte as hexadecimal when the format cannot be determined or is not supported. This option overrides the setting in bAutoViewAsText.

- For the `nViewAsMode` member, the `VIEW_MODE_NORMAL`, `VIEW_MODE_TEXT`, and `VIEW_MODE_HEX` options are mutually exclusive; and the `VIEW_MODE_AUTO_TEXT` and `VIEW_MODE_AUTO_HEX` options are mutually exclusive. This means you can set a maximum of two options at one time. For example, you can set `nViewAsMode` as:

      nViewAsMode= VIEW_MODE_TEXT | VIEW_MODE_AUTO_HEX

  This configuration results in the following behavior:

File characteristic | Behavior
--- | ---
The file format cannot be determined | The `VAPI_RETURN_UNKNOWN_FORMAT` message is returned, and the file is displayed as hexadecimal.
The file format can be determined, but is not supported | The`VAPI_RETURN_NO_VIEWER` message is returned, and the file is displayed as ASCII text.
The file format can be determined and is supported | The `VAPI_RETURN_SUCCESS` message is returned, and the file is displayed as ASCII text.

- The `nFlags` member can be one of the following options:

  Options for nFlags
  Option | Description
  --- | ---
  `VAPIDF_FLAGS_OPEN_FORMAT_ONLY` | Opens a document to determine the document format, regardless of whether the document is supported for viewing. After the document is opened, you can then call the VAPIMWP_INIT_GETDOCFORMAT message to get the format information. This flag does not create a Viewer window.
  `VAPIDF_FLAGS_OPEN_WITHOUT_VIEW` | Opens a document in a hidden viewer window. Use this flag to process a document (print, convert, and so on) without viewing. (You must also set the `bWait` member to `TRUE`.) For example, to print a document, set the `VAPIDF_FLAGS_OPEN_WITHOUT_VIEW` flag, and then send the `VAPIMWP_PRINT_PRINT` message.
  `VAPIDF_FLAGS_OPEN_VAPI_ONLY` | Opens a document without viewing and returns format information with the notification message `VAPINMWP_INIT_DOCTYPE`. This flag does not create a Viewer window.
  `VAPIDF_FLAGS_NO_UI` | Suppresses GUI elements that are not called explicitly. For example, if you set this flag and the document format is not supported, the "unsupported format" dialog box does not display. However, if you set this flag and send the VAPI message to request the SaveAs dialog box, the SaveAs dialog box displays.
  `VAPIDF_FLAGS_INCL_REVISION_MARK` | Displays the deleted content, revision marks, and revision tracking information in a document. See View Deleted Items and Document Revision Marks.

_FT_HTML5_bannerTitle.htm