Edit

Share via

ITfContext::RequestEditSession method (msctf.h)

  • Article

Obtains access to the document text and properties.

Syntax

HRESULT RequestEditSession(
  [in]  TfClientId     tid,
  [in]  ITfEditSession *pes,
  [in]  DWORD          dwFlags,
  [out] HRESULT        *phrSession
);

Parameters

[in] tid

Contains a TfClientId value that identifies the client to establish the edit session with.

[in] pes

Pointer to an ITfEditSession interface called to perform the edit session.

[in] dwFlags

Contains one or more of the following values.

Value Meaning
TF_ES_ASYNCDONTCARE
 The edit session can occur synchronously or asynchronously, at the discretion of the TSF manager. The manager will attempt to schedule a synchronous edit session for improved performance. This value cannot be combined with the TF_ES_ASYNC or TF_ES_SYNC values.
TF_ES_SYNC
 The edit session must be synchronous or the request will fail (with TF_E_SYNCHRONOUS). This flag should only be used in documented situations (such as keystroke handling) where it can be expected to succeed. Otherwise the call will likely fail. This value cannot be combined with the TF_ES_ASYNCDONTCARE or TF_ES_ASYNC values.
TF_ES_READ
 Requests read-only access to the context.
TF_ES_READWRITE
 Requests read/write access to the context.
TF_ES_ASYNC
 The edit session must be asynchronous or the request fails. This value cannot be combined with the TF_ES_ASYNCDONTCARE or TF_ES_SYNC values.

[out] phrSession

Address of an HRESULT value that receives the result of the edit session request. The value received depends upon the type of edit session requested.

  • If an asynchronous edit session is requested and can be established, receives TF_S_ASYNC.
  • If a synchronous edit session is requested and cannot be established, receives TF_E_SYNCHRONOUS.
  • If the TF_ES_READWRITE flag is specified and the document is read-only, receives TS_E_READONLY.
  • If a synchronous edit session is established, receives the return value of the ITfEditSession::DoEditSession.

Return value

This method can return one of these values.

Value Description
S_OK
 The method was successful. phrSession contains more result data for the method.
TF_E_LOCKED
 The caller is within the context of another text service which already holds a lock.
TF_E_DISCONNECTED
 The context is not on a document stack.
E_INVALIDARG
 One or more parameters are invalid.
E_OUTOFMEMORY
 A memory allocation failure occurred.

Remarks

Pending asynchronous edit sessions are processed in the order received. Synchronous edit sessions are processed before any pending asynchronous edit sessions.

A text service can request an edit session within the context of an existing edit session, provided a write access session is not requested within a read-only session. Calls to this method within the context of an edit session established by another text service will fail with TF_E_LOCKED.

A synchronous read/write request will fail if made when processing one of the following notifications.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps | UWP apps]
Minimum supported server Windows 2000 Server [desktop apps | UWP apps]
Target Platform Windows
Header msctf.h
DLL Msctf.dll
Redistributable TSF 1.0 on Windows 2000 Professional

See also

ITfContext interface, ITfEditSession interface, ITfStatusSink::OnStatusChange, ITfTextEditSink::OnEndEdit, ITfTextLayoutSink::OnLayoutChange