| title | description | ms.assetid | keywords | ms.topic | ms.date | |||
|---|---|---|---|---|---|---|---|---|
Channel (Windows Web Services) |
Channels encapsulate a communication context between two or more parties and are used to send and receive messages. |
5a04580d-c89f-4505-a4b7-0724ffb788fd |
|
article |
05/31/2018 |
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. |