The
ITextDocument::Open method opens a specified document. There are parameters to specify access and sharing privileges, creation and conversion of the file, as well as the code page for the file.
Syntax
STDMETHODIMP Open(
VARIANT *pVar,
long Flags,
long CodePage
);
Parameters
- pVar
-
[in] Pointer to a VARIANT that specifies the name of the file to open.
- Flags
-
File creation, open, share, and conversion flags. Default value is zero, which gives read/write access and read/write sharing, open always, and automatic recognition of the file format (unrecognized file formats are treated as text). Other values are defined in the following groups.
- Any combination of these values may be used.
tomReadOnly- Read only.
tomShareDenyRead- Other programs cannot read.
tomShareDenyWrite- Other programs cannot write.
tomPasteFile- Replaces selection with file.
- These values are mutually exclusive.
tomCreateNew- Creates new file; fails if it exists already.
tomCreateAlways- Creates new file; it destroys an existing file.
tomOpenExisting- Opens existing file; otherwise fails.
tomOpenAlways- Opens existing file; otherwise creates new.
tomTruncateExisting- Opens existing file but truncates it to zero length.
tomRTF- Opens as Rich Text Format (RTF).
tomText- Opens as text (ANSI or Unicode).
tomHTML- Opens as HTML
tomWordDocument- Opens as Microsoft Word document.
- CodePage
-
Code page to use for the file. Zero (the default value) means CP_ACP (ANSI code page) unless the file begins with a Unicode byte-order mark (BOM) 0xfeff, in which case the file is considered to be Unicode. Note that code page 1200 is Unicode, CP_UTF8 is 8-bit Unicode Transformation Format (UTF-8).
Return Value
The return value can be an HRESULT value that corresponds to a system error or Component Object Model (COM) error code, including one of the following values.
| S_OK | Method succeeds |
| E_INVALIDARG | Invalid argument. |
| E_OUTOFMEMORY | Insufficient memory. |
| E_NOTIMPL | Feature not implemented. |
Remarks
If a document is created with the ITextDocument::New method and the zero values are used, then the Text Object Model (TOM) engine has to choose which flags and code page to use. UTF-8 RTF (defined below) is an attractive default.
Microsoft Rich Edit 3.0 defines a control word, \urtf8, which should be used instead of \rtf1. This means the file is encoded in UTF-8. On input, RTF files contain the relevant code-page information, but this can be changed for saving purposes, thereby allowing one version to be translated to another.
If the tomPasteFile flag is not set in the Flags parameter, the method first closes the current document after saving any unsaved changes.
A file is recognized as a Unicode text file if it starts with the Unicode BOM 0xfeff. The ITextDocument::Open method strips off this Unicode BOM on input and ITextDocument::Save applies it on output. See the comments on the ITextDocument::Save method, which discuss putting the Unicode BOM at the beginning of Unicode plain-text files. The conversion values tomRTF, tomHTML, and tomWordDocument are used primarily for the Save method, since these formats are easily recognized on input.
Errors are reported by negative values, but since file operations have many kinds of errors, you may not need all of the error information provided. In particular, you may not care (or you may already know) which file facility is used, namely Microsoft Windows (pVar.vt = VT_BSTR) or OLE storage for IStorage. By masking off bit 18 of an HRESULT value, you can ignore the difference and compare to its STG_E_xxx value. For example:
HRESULT hr;
VARIANT Var;
VariantInit(&Var)
Var.vt = VT_BSTR;
Var.bstrVal = SysAllocString(L"test.txt"); // Use file command
hr = pDoc->Open(&Var, tomOpenExisting, 0);
hr &= ~0x40000; // Mask off bit 18
if(hr == STG_E_FILENOTFOUND)
{
...// the rest of the code
}
Method Information
| Minimum DLL Version | msftedit.dll |
|---|
| Header | Declared in Tom.h |
|---|
| Minimum operating systems |
Windows 95 with Rich Edit 2.0, Windows 98, Windows NT 4.0 |
|---|
See Also