WS_MESSAGE_PROPERTY_ID enumeration (webservices.h)

  • Article

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

Syntax

typedef enum {
  WS_MESSAGE_PROPERTY_STATE = 0,
  WS_MESSAGE_PROPERTY_HEAP = 1,
  WS_MESSAGE_PROPERTY_ENVELOPE_VERSION = 2,
  WS_MESSAGE_PROPERTY_ADDRESSING_VERSION = 3,
  WS_MESSAGE_PROPERTY_HEADER_BUFFER = 4,
  WS_MESSAGE_PROPERTY_HEADER_POSITION = 5,
  WS_MESSAGE_PROPERTY_BODY_READER = 6,
  WS_MESSAGE_PROPERTY_BODY_WRITER = 7,
  WS_MESSAGE_PROPERTY_IS_ADDRESSED = 8,
  WS_MESSAGE_PROPERTY_HEAP_PROPERTIES = 9,
  WS_MESSAGE_PROPERTY_XML_READER_PROPERTIES = 10,
  WS_MESSAGE_PROPERTY_XML_WRITER_PROPERTIES = 11,
  WS_MESSAGE_PROPERTY_IS_FAULT = 12,
  WS_MESSAGE_PROPERTY_MAX_PROCESSED_HEADERS = 13,
  WS_MESSAGE_PROPERTY_USERNAME = 14,
  WS_MESSAGE_PROPERTY_ENCODED_CERT = 15,
  WS_MESSAGE_PROPERTY_TRANSPORT_SECURITY_WINDOWS_TOKEN = 16,
  WS_MESSAGE_PROPERTY_HTTP_HEADER_AUTH_WINDOWS_TOKEN = 17,
  WS_MESSAGE_PROPERTY_MESSAGE_SECURITY_WINDOWS_TOKEN = 18,
  WS_MESSAGE_PROPERTY_SAML_ASSERTION = 19,
  WS_MESSAGE_PROPERTY_SECURITY_CONTEXT = 20,
  WS_MESSAGE_PROPERTY_PROTECTION_LEVEL = 21
} WS_MESSAGE_PROPERTY_ID;

Constants

 
WS_MESSAGE_PROPERTY_STATE
Value: 0
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
Value: 1
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 freed
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
Value: 2
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
Value: 3
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
Value: 4
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
Value: 5
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 containing 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
Value: 6
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
Value: 7
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
Value: 8
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
Value: 9
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
Value: 10
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
Value: 11
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 writers 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
Value: 12
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
Value: 13
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
Value: 14
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
Value: 15
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
Value: 16
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
Value: 17
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 WsSetMessageProperty to 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
Value: 18
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
Value: 19
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
Value: 20
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
Value: 21
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 determine 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

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