VirtualChannelOpenEvent

  • Article

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.

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. pData is a pointer to a chunk of the data. dataLength indicates the size of this chunk. totalLength 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. pData 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. pData 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.

    Note that 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] The size, in bytes, of the data in the pData buffer.

  • totalLength
    [in] 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 will be set. 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 Values

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 will not be called with the same type it is currently processing.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Cchannel.h.
Link Library: Developer implemented.

See Also

RDP Functions

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.