Export (0) Print
Expand All
Expand Minimize

WS_MESSAGE_PROPERTY_ID enumeration

Each message property is of type WS_MESSAGE_PROPERTY, is identified by an ID, and has an associated value.

Syntax


enum WS_MESSAGE_PROPERTY_ID {  WS_MESSAGE_PROPERTY_STATE, 
  WS_MESSAGE_PROPERTY_HEAP, 
  WS_MESSAGE_PROPERTY_ENVELOPE_VERSION, 
  WS_MESSAGE_PROPERTY_ADDRESSING_VERSION, 
  WS_MESSAGE_PROPERTY_HEADER_BUFFER, 
  WS_MESSAGE_PROPERTY_HEADER_POSITION, 
  WS_MESSAGE_PROPERTY_BODY_READER, 
  WS_MESSAGE_PROPERTY_BODY_WRITER, 
  WS_MESSAGE_PROPERTY_IS_ADDRESSED, 
  WS_MESSAGE_PROPERTY_HEAP_PROPERTIES, 
  WS_MESSAGE_PROPERTY_XML_READER_PROPERTIES, 
  WS_MESSAGE_PROPERTY_XML_WRITER_PROPERTIES, 
  WS_MESSAGE_PROPERTY_IS_FAULT, 
  WS_MESSAGE_PROPERTY_MAX_PROCESSED_HEADERS, 
  WS_MESSAGE_PROPERTY_USERNAME, 
  WS_MESSAGE_PROPERTY_ENCODED_CERT, 
  WS_MESSAGE_PROPERTY_TRANSPORT_SECURITY_WINDOWS_TOKEN, 
  WS_MESSAGE_PROPERTY_HTTP_HEADER_AUTH_WINDOWS_TOKEN, 
  WS_MESSAGE_PROPERTY_MESSAGE_SECURITY_WINDOWS_TOKEN, 
  WS_MESSAGE_PROPERTY_SAML_ASSERTION, 
  WS_MESSAGE_PROPERTY_SECURITY_CONTEXT, 
  WS_MESSAGE_PROPERTY_PROTECTION_LEVEL 

};

Constants

WS_MESSAGE_PROPERTY_STATE

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is the current WS_MESSAGE_STATE of the message.

This property is available in all message states.

WS_MESSAGE_PROPERTY_HEAP

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is the WS_HEAP of the message. The heap is owned by the message. A user of a message is free to make additional allocations within this heap. Allocations within the heap are free'd when a message is reset/freed.

The user of the returned heap should not call WsResetHeap on the heap. This will result in undefined behavior.

The message object will not use the heap object unless one of the message APIs is invoked.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY. Using the heap of an empty message will result in undefined behavior.

WS_MESSAGE_PROPERTY_ENVELOPE_VERSION

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is the WS_ENVELOPE_VERSION of the message.

When creating a message using WsCreateMessage, the envelope version is specified as an explicit parameter (instead of as a property).

This property may be specified when message properties are specified using the WS_MESSAGE_PROPERTIES structure.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_ADDRESSING_VERSION

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is the WS_ADDRESSING_VERSION of the message.

When creating a message using WsCreateMessage, the addressing version is specified as an explicit parameter (instead of as a property).

This property may be specified when message properties are specified using the WS_MESSAGE_PROPERTIES structure.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_HEADER_BUFFER

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_XML_BUFFER that holds the headers of the message (as well as the envelope and body elements).

This buffer is valid until the message is reset/freed.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_HEADER_POSITION

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is the WS_XML_NODE_POSITION of the header element within the header buffer (the element that contains all the message headers as children). The header buffer itself can be obtained using WS_MESSAGE_PROPERTY_HEADER_BUFFER.

An application can use the WS_XML_NODE_POSITION returned as a starting point when reading or writing headers manually (when not using WsSetHeader, WsGetHeader, WsGetCustomHeader or WsAddCustomHeader). For example, the position can be passed to WsSetWriterPosition or WsSetReaderPosition to position an XML Reader or XML Writer within the WS_XML_BUFFER containining the headers. Additionally, WsMoveReader or WsMoveWriter can be used to move relative to the position that was set.

When the headers of a message are read (via WsReadMessageStart or WsReadEnvelopeStart, a header element is automatically added to the header buffer if one is not present in the message being read. When a message is initialized (via WsInitializeMessage), a header element is added automatically to the message.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

The header position is valid until the message is reset or freed.

WS_MESSAGE_PROPERTY_BODY_READER

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_XML_READER that can be used to read the body of the message.

The reader is owned by the message object, and is valid only until either WsFreeMessage or WsResetMessage are called.

This property is only available when the message is in WS_MESSAGE_STATE_READING state.

WS_MESSAGE_PROPERTY_BODY_WRITER

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_XML_WRITER that can be used to write the body of the message.

This property is only available when the message is in WS_MESSAGE_STATE_WRITING state.

The writer is owned by the message object, and is valid only until either WsFreeMessage or WsResetMessage are called.

WS_MESSAGE_PROPERTY_IS_ADDRESSED

This property is used with WsGetMessageProperty.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a BOOL indicating whether the message has been addressed.

When a message is created or reset, this property is set to FALSE.

When a message is read (WsReadMessageStart or WsReadEnvelopeStart, then this property is set to TRUE.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

See WsAddressMessage for more information.

WS_MESSAGE_PROPERTY_HEAP_PROPERTIES

This property is used with WsCreateMessage to specify the properties of the WS_HEAP associated with the message.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is of type WS_HEAP_PROPERTIES.

The heap is used to buffer the headers of the message.

The following heap properties may be specified:

WS_MESSAGE_PROPERTY_XML_READER_PROPERTIES

This property is used with WsCreateMessage to specify properties that apply to XML Readers that are used with the message.

These XML Reader properties are used by the message object when reading headers. In addition, channels use these properties for the readers that they create to read messages.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is of type WS_XML_READER_PROPERTIES.

The following properties may be specified:

WS_MESSAGE_PROPERTY_XML_WRITER_PROPERTIES

This property is used with WsCreateMessage to specify the properties of the XML Writers that are used with the message.

These XML Writer properties are used by the message object when writing headers. In addition, channels use these properties for the wrtiers that they create to write messages.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is of type WS_XML_WRITER_PROPERTIES.

The following properties may be specified:

WS_MESSAGE_PROPERTY_IS_FAULT

This property is used with WsGetMessageProperty or WsSetMessageProperty to indicate whether a message contains a fault.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a BOOL.

When a message is read (WsReadMessageStart or WsReadEnvelopeStart), this property is set according to whether the first element of the body is a fault element. An application can test this property as a way of deciding whether to read the body as a fault. To read the body as a fault, use WsReadBody with WS_FAULT_TYPE to obtain a WS_FAULT.

When a message is written (WsWriteMessageStart or WsWriteEnvelopeStart) this property can be used to indicate whether or not the application will write a fault in the body. Some channels will use this information in order to determine how to send the message. For example, HTTP will send a 500 status code for faults instead of 200.

When a message is initialized using WsInitializeMessage with WS_FAULT_MESSAGE, the property is set to TRUE. For other WS_MESSAGE_INITIALIZATION values, the property is set to FALSE.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_MAX_PROCESSED_HEADERS

This property is used with WsCreateMessage to specify the maximum number of headers that will be allowed when processing the message headers.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a ULONG.

The purpose of this limit is to put an upper bound on the number of iterations spent scanning for a header.

Since an application can directly modify the contents of the header buffer, this limit is not enforced in all cases. It is only enforced when one of the header access APIs are used (WsSetHeader, WsGetHeader, WsGetCustomHeader, or WsGetMappedHeader).

The default value is 64.

WS_MESSAGE_PROPERTY_USERNAME

This property is used with WsGetMessageProperty to retrieve the sender's username from a received message, if username/password based security is on, or if a custom channel has set the value.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_STRING structure.

The returned value is good until the message is freed or reset.

A custom channel can use WsSetMessageProperty to set the sender's username from the message if it supports username/password based security. The function will make a copy of the value specified.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_ENCODED_CERT

This property is used with WsGetMessageProperty to retrieve the sender's certificate from a received message as encoded bytes, if a certificate-based security mode (such as SSL) is on, or if a custom channel has set the value.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_BYTES structure.

The returned value is good until the message is freed or reset.

A custom channel can use WsSetMessageProperty to set the sender's certificate from a received message if it supports a certificate-based security mode. The function will make a copy of the value specified.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_TRANSPORT_SECURITY_WINDOWS_TOKEN

This property is used with WsGetMessageProperty to retrieve the Windows token representing the sender from a received message. This property is available in the following cases:

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a HANDLE.

The returned value is good until the message is freed or reset.

A custom channel can use WsSetMessageProperty to set the sender's certificate from a received message if it supports a certificate-based security mode. The function will duplicate the handle specified.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_HTTP_HEADER_AUTH_WINDOWS_TOKEN

This property is used with WsGetMessageProperty to retrieve the Windows token representing the sender from a received message, if the WS_HTTP_HEADER_AUTH_SECURITY_BINDING is used, or if a custom channel has set the value.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a HANDLE.

The returned value is good until the message is freed or reset.

A custom channel can use WsSetMessagePropertyto set the windows token representing the sender from a received message. The function will duplicate the handle specified.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_MESSAGE_SECURITY_WINDOWS_TOKEN

This property is used with WsGetMessageProperty to retrieve the Windows token representing the sender from a received message, if a message security binding such as WS_KERBEROS_APREQ_MESSAGE_SECURITY_BINDING is used, or if a custom channel has set the value.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a HANDLE.

The returned value is good until the message is freed or reset.

A custom channel can use WsSetMessageProperty to set the token representing the sender from a received message. The function will duplicate the handle specified.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_SAML_ASSERTION

This property is used with WsGetMessageProperty to retrieve the SAML assertion representing the sender from a received message, if the WS_SAML_MESSAGE_SECURITY_BINDING is used on the server side, or if a custom channel has set the value.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_XML_BUFFER.

The returned value is good until the message is freed or reset.

A custom channel can use WsSetMessageProperty to set the SAML assertion representing the sender from a received message. The function will duplicate the buffer specified.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

WS_MESSAGE_PROPERTY_SECURITY_CONTEXT

This property is used with WsGetMessageProperty to retrieve the secure conversation handle if the WS_SECURITY_CONTEXT_MESSAGE_SECURITY_BINDING is used on the server side.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_SECURITY_CONTEXT.

The returned value is good until the message is freed or reset.

WS_MESSAGE_PROPERTY_PROTECTION_LEVEL

This property is used with WsGetMessageProperty to retrieve the message's security protection level.

The accompanying value member of the WS_MESSAGE_PROPERTY structure is a WS_PROTECTION_LEVEL value.

If the channel does not use security, or if security verification failed, the protection level is set to WS_PROTECTION_LEVEL_NONE. Otherwise it is set to the level requested by the application.

This property may be used to dermine the status of the security verification when WS_CHANNEL_PROPERTY_ALLOW_UNSECURED_FAULTS is set to FALSE.

A custom channel can use WsSetMessageProperty to set the protection level of a received message.

This property is available in all message states except WS_MESSAGE_STATE_EMPTY.

Requirements

Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]

Header

WebServices.h

 

 

Community Additions

ADD
Show:
© 2014 Microsoft