Share via

VirtualChannelOpenEvent

  • Article

Other versions of this page are also available for the following:

Windows Mobile Not SupportedWindows Embedded CE Supported

8/28/2008

This function is an application-defined callback function. Terminal Services calls this function to notify the client DLL of events for a specific virtual channel.

The PCHANNEL_OPEN_EVENT_FN type defines a pointer to this callback function. VirtualChannelOpenEvent is a placeholder for the application-defined or library-defined function name.

Syntax

VOID VCAPITYPE VirtualChannelOpenEvent(
  DWORD openHandle,
  UINT event,
  LPVOID pData,
  UINT32 dataLength,
  UINT32 totalLength,
  UINT32 dataFlags
);

Parameters

  • openHandle
    [in] Handle to the virtual channel. This is the handle returned in the pOpenHandle parameter of the VirtualChannelOpen function.

  • event
    [in] Indicates the event that caused the notification. The following table shows possible values for this parameter.

    Value Description

    CHANNEL_EVENT_DATA_RECEIVED

    The virtual channel received data from the server end. The pData parameter is a pointer to a chunk of the data. The dataLength parameter indicates the size of this chunk. The totalLength parameter indicates the total size of the data written by the server.

    CHANNEL_EVENT_WRITE_CANCELLED

    A write operation started by a VirtualChannelWrite function call has been canceled. The pData parameter is the value specified in the pUserData parameter of VirtualChannelWrite.

    A write operation is canceled when the client session is disconnected. This notification enables you to free any memory associated with the write operation.

    CHANNEL_EVENT_WRITE_COMPLETE

    A write operation started by a VirtualChannelWrite function call has been completed. The pData parameter is the value specified in the pUserData parameter of VirtualChannelWrite.

  • pData
    [in] Pointer to additional data for the event. The type of data depends on the event, as described in the event descriptions.

    If the event is CHANNEL_EVENT_DATA_RECEIVED, the data written by the server is broken into chunks of not more than CHANNEL_CHUNK_LENGTH bytes. The dataFlags parameter indicates whether the current chunk is at the beginning, middle, or end of the block of data written by the server.

    The size of this parameter can be greater than the value specified by the dataLength parameter. The application should read only the number of bytes specified by the dataLength parameter.

  • dataLength
    [in] Specifies the size, in bytes, of the data in the pData buffer.
  • totalLength
    [in] Specifies the total size, in bytes, of the data written by a single write operation to the server end of the virtual channel.

  • dataFlags
    [in] Provides information about the chunk of data being received in a CHANNEL_EVENT_DATA_RECEIVED event. The following table shows the bit flags that are set.

    Note

    Do not make direct comparisons using the == operator; use the methods described in the following table to compare the corresponding flag value.

    Value Description

    CHANNEL_FLAG_FIRST

    The chunk is the beginning of the data written by a single write operation.

    Use bitwise comparisons when comparing this flag.

    CHANNEL_FLAG_LAST

    The chunk is the end of the data written by a single write operation.

    Use bitwise comparisons when comparing this flag.

    CHANNEL_FLAG_MIDDLE

    This flag is set by default. The chunk is in the middle of a block of data written by a single write operation.

    Do not use bitwise comparisons to compare this flag value directly. Instead, use bitwise comparisons to determine that the flag value is not CHANNEL_FLAG_FIRST or CHANNEL_FLAG_LAST. This is done by using the following comparison:

    Result = !(flags & CHANNEL_FLAG_FIRST) && !(flags & CHANNEL_FLAG_LAST)

    CHANNEL_FLAG_ONLY

    Combines the CHANNEL_FLAG_FIRST and CHANNEL_FLAG_LAST values. The chunk contains all the data from a single write operation.

    Use bitwise comparisons when comparing this flag.

Return Value

None.

Remarks

The client DLL uses VirtualChannelOpen to register a VirtualChannelOpenEvent function for a specific virtual channel.

You can use the same VirtualChannelOpenEvent function for multiple calls to VirtualChannelOpen.

This function can be called with a different event type while it is executing. For example, it might be called with CHANNEL_EVENT_WRITE_COMPLETE or CHANNEL_EVENT_WRITE_CANCELLED while it is processing the CHANNEL_EVENT_DATA_RECEIVED event. This function is not called with the same type it is currently processing.

Requirements

Header cchannel.h
Library Developer Implemented
Windows Embedded CE Windows CE .NET 4.0 and later

See Also

Reference

RDP Functions