Channel (Windows Web Services)

Channels encapsulate a communication context between two or more parties and are used to send and receive messages.

On the client, use WsCreateChannel to create a channel. On the server, use WsCreateChannelForListener to create a channel that can be accepted by the client using a listener.

When you create a channel, you specify the following information, which determines both the local behavior of the channel and the wire protocol to be used.

  • A WS_CHANNEL_TYPE, which identifies the message exchange pattern of the channel.
  • A WS_CHANNEL_BINDING, which identifies the transfer protocol to use.
  • A WS_SECURITY_DESCRIPTION, which specifies the security used for the channel. When creating channels for use in a server, this is specified once for all channels that will be accepted for a given listener.
  • A set WS_CHANNEL_PROPERTYs, which specify additional optional settings (for a list of these settings, see the WS_CHANNEL_PROPERTY_ID enumerations).

Before you use the channel, you must open it by calling the WsOpenChannel function, and specifying the channel and endpoint address, along with other, optional information.

For information on the state transitions for a channel, see the Channel States topic.

For more information on channels, see the Channel Layer Overview topic.

The following API elements are used with channels.

Callback Description
WS_ABANDON_MESSAGE_CALLBACK Handles the WsAbandonMessage call for a channel with custom channel binding.
WS_ABORT_CHANNEL_CALLBACK Handles the WsAbortChannel call for a channel with custom channel binding.
WS_CLOSE_CHANNEL_CALLBACK Handles the WsCloseChannel call for a channel with custom channel binding.
WS_CREATE_CHANNEL_CALLBACK Handles the WsCloseChannel call for a channel with custom channel binding.
WS_CREATE_DECODER_CALLBACK Handles creating a decoder instance.
WS_CREATE_ENCODER_CALLBACK Handles creating an encoder instance.
WS_DECODER_DECODE_CALLBACK Decodes a message.
WS_DECODER_END_CALLBACK Decodes the end of a message.
WS_DECODER_GET_CONTENT_TYPE_CALLBACK Gets the content type of the message.
WS_DECODER_START_CALLBACK Starts decoding a message.
WS_ENCODER_ENCODE_CALLBACK Encodes a message.
WS_ENCODER_END_CALLBACK Encodes the end of a message.
WS_ENCODER_GET_CONTENT_TYPE_CALLBACK Gets the content type of the message.
WS_ENCODER_START_CALLBACK Starts encoding a message.
WS_FREE_CHANNEL_CALLBACK Handles the WsFreeChannel call for a channel with custom channel binding.
WS_FREE_DECODER_CALLBACK Handles freeing a decoder instance.
WS_FREE_ENCODER_CALLBACK Handles freeing an encoder instance.
WS_GET_CHANNEL_PROPERTY_CALLBACK Handles the WsGetChannelProperty call for a channel with custom channel binding.
WS_HTTP_REDIRECT_CALLBACK Invoked when a message is about to be automatically redirected to another service utilizing HTTP auto redirect functionality as described in RFC2616.
WS_OPEN_CHANNEL_CALLBACK Handles the WsOpenChannel call for a channel with custom channel binding.
WS_READ_MESSAGE_END_CALLBACK Handles the WsReadMessageEnd call for a channel with custom channel binding.
WS_READ_MESSAGE_START_CALLBACK Handles the WsReadMessageEnd call for a channel with custom channel binding.
WS_RESET_CHANNEL_CALLBACK Handles the WsResetChannel call for a channel with custom channel binding.
WS_SET_CHANNEL_PROPERTY_CALLBACK Handles the WsSetChannelProperty call for a channel with custom channel binding.
WS_SHUTDOWN_SESSION_CHANNEL_CALLBACK Handles the WsShutdownSessionChannel call for a channel with custom channel binding.
WS_WRITE_MESSAGE_END_CALLBACK Handles the WsWriteMessageEnd call for a channel with custom channel binding.
WS_WRITE_MESSAGE_START_CALLBACK Handles the WsWriteMessageStart call for a channel with custom channel binding.

 

Enumeration Description
WS_CHANNEL_BINDING Indicates the protocol stack to use for the channel.
WS_CHANNEL_PROPERTY_ID Identifies each channel property by an ID.
WS_CHANNEL_STATE The state of the channel.
WS_CHANNEL_TYPE Indicates the basic characteristics of the channel, such as whether it is sessionful, and what directions of communication are supported.
WS_ENCODING The different encodings (message formats).
WS_RECEIVE_OPTION Specifies whether a message is required when receiving from a channel.
WS_TRANSFER_MODE Specifies whether messages that are sent or received are streamed or buffered.

 

Function Description
WsAbandonMessage Skips the remainder of a message for a channel.
WsAbortChannel Aborts all pending I/O on a specified channel and sets the channel state to WS_CHANNEL_STATE_FAULTED.
WsCloseChannel Closes a channel when it is no longer needed.
WsCreateChannel Creates a channel.
WsCreateChannelForListener Creates a channel for a listener.
WsFreeChannel Releases the memory resources associated with a channel.
WsGetChannelProperty Retrieves a property of the Channel referenced by the channel parameter.
WsOpenChannel Opens a channel to an endpoint.
WsReadMessageEnd Reads the closing elements of a message from a channel.
WsReadMessageStart Reads the headers of the next message from the channel and prepares to read the body elements.
WsReceiveMessage Receives a message and deserializes the body of the message as a value.
WsRequestReply Sends a request message and receives a correlated reply message.
WsResetChannel Reset a channel so it can be reused.
WsSendMessage Sends a message on a channel using serialization to write the body element.
WsSendReplyMessage Sends a message that is a reply to a received message.
WsSetChannelProperty Sets a property of a channel.
WsSetMessageProperty Sets a property of a message.
WsWriteMessageEnd Writes the closing elements of a message to the channel.
WsWriteMessageStart Write out the headers of a message to the channel and prepares to write the body elements.

 

Handle Description
WS_CHANNEL An opaque type used to reference a channel.

 

Structure Description
WS_CHANNEL_DECODER A set of callbacks that transform the content type and encoded bytes of a received message.
WS_CHANNEL_ENCODER A set of callbacks that can transform the content type and encoded bytes of a sent message.
WS_CHANNEL_PROPERTIES A set of WS_CHANNEL_PROPERTY structures.
WS_CHANNEL_PROPERTY A channel-specific setting.
WS_CUSTOM_CHANNEL_CALLBACKS A set of callbacks that form the implementation of a custom channel.
WS_CUSTOM_HTTP_PROXY used to specify the custom proxy for the channel, using the WS_CHANNEL_PROPERTY_CUSTOM_HTTP_PROXY value of the WS_CHANNEL_PROPERTY_ID enumeration.
WS_HTTP_HEADER_MAPPING Represents an individual header that is mapped as part of WS_HTTP_MESSAGE_MAPPING.
WS_HTTP_MESSAGE_MAPPING Information about how an HTTP request or response should be represented in a message object.
WS_HTTP_REDIRECT_CALLBACK_CONTEXT Specifies the callback function and state for controlling the HTTP automatic redirection behavior.
WS_MESSAGE_DESCRIPTION The schema for the input and output WS_MESSAGE for a given operation description.