Edit

Share via

WS_CHANNEL_ENCODER structure (webservices.h)

  • Article

A structure that is used to specify a set of callbacks that can transform the content type and encoded bytes of a sent message.

Syntax

typedef struct _WS_CHANNEL_ENCODER {
  void                                 *createContext;
  WS_CREATE_ENCODER_CALLBACK           createEncoderCallback;
  WS_ENCODER_GET_CONTENT_TYPE_CALLBACK encoderGetContentTypeCallback;
  WS_ENCODER_START_CALLBACK            encoderStartCallback;
  WS_ENCODER_ENCODE_CALLBACK           encoderEncodeCallback;
  WS_ENCODER_END_CALLBACK              encoderEndCallback;
  WS_FREE_ENCODER_CALLBACK             freeEncoderCallback;
} WS_CHANNEL_ENCODER;

Members

createContext

A context that will be passed to the WS_CREATE_ENCODER_CALLBACK.

createEncoderCallback

A WS_CREATE_ENCODER_CALLBACK callback that creates an instance of an encoder.

encoderGetContentTypeCallback

A WS_ENCODER_GET_CONTENT_TYPE_CALLBACK callback that is invoked when a message is to be encoded.

encoderStartCallback

A WS_ENCODER_START_CALLBACK callback that is invoked to start encoding a message.

encoderEncodeCallback

A WS_ENCODER_ENCODE_CALLBACK callback that is invoked to encode a message.

encoderEndCallback

A WS_ENCODER_END_CALLBACK callback that is invoked to at the end of encoding a message.

freeEncoderCallback

A WS_FREE_ENCODER_CALLBACK callback that frees an instance of an encoder.

Remarks

A WS_CHANNEL may wish to compress, modify, or otherwise transform the encoded bytes of a message before they are sent. A WS_CHANNEL_ENCODER provides the necessary hooks to intercept and perform these modifications.

When creating the channel, the WS_CHANNEL_PROPERTY_ENCODER should be set with the appropriate functions.

The grammar for the encoder callbacks is:


encodercalls := create encoderloop* free
encoderloop  := getcontenttype
             |  getcontenttype encodestart
             |  getcontenttype encodestart (encode*)
             |  getcontenttype encodestart (encode*) encodeend

The encoder may not see the full encode sequence for a message if the channel or the encoder encounters an error while writing the message. An encoder must be prepared to handle transitioning to the appropriate state based upon the callbacks invoked.

When using WS_TCP_CHANNEL_BINDING with WS_CHANNEL_TYPE_SESSION, the content type is fixed for the channel. In this case, the WS_ENCODER_GET_CONTENT_TYPE_CALLBACK must return exactly the same value for the content type of every message.

When the channel is finished using the encoder instance it will free it via the WS_FREE_ENCODER_CALLBACK.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Header webservices.h