WsGetMappedHeader function

Finds a mapped header in the message and deserializes it.

Syntax


HRESULT WINAPI  WsGetMappedHeader(
  _In_     WS_MESSAGE*                message,
  _In_     const WS_XML_STRING*       headerName,
  _In_     WS_REPEATING_HEADER_OPTION repeatingOption,
  _In_     ULONG                      headerIndex,
  _In_     WS_TYPE                    valueType,
  _In_     WS_READ_OPTION             readOption,
  _In_opt_ WS_HEAP*                   heap,
           void*                      value,
  _In_     ULONG                      valueSize,
  _In_opt_ WS_ERROR*                  error
);

Parameters

message [in]

The message containing the header.

The message can be in any state but WS_MESSAGE_STATE_EMPTY.

headerName [in]

The name of the mapped header.

repeatingOption [in]

Whether the header may appear more than once in the message.

If WS_REPEATING_HEADER is used, then the header index indicates which of the headers with the specified headerName to return.

If WS_SINGLETON_HEADER is used, then the headerIndex must be zero.

headerIndex [in]

The zero-based index of the header within the set of headers with the specified headerName.

valueType [in]

The type of value to deserialize.

readOption [in]

Whether the value is required, and how to allocate the value. See WS_READ_OPTION for more information.

If the header is optional (may appear zero or one times), then WS_READ_OPTIONAL_POINTER can be used.

heap [in, optional]

The heap to store the deserialized header data in. If this is NULL, then the message heap will be used.

value

The interpretation of this parameter depends on the WS_READ_OPTION.

valueSize [in]

The interpretation of this parameter depends on the WS_READ_OPTION.

error [in, optional]

Specifies where additional error information should be stored if the function fails.

Return value

This function can return one of these values.

Return code	Description
WS_E_INVALID_FORMAT	The header does not exist, and is required. The input data was not in the expected format. WS_SINGLETON_HEADER was specified, and there are multiple instances of the header with the specified name in the message.
WS_E_QUOTA_EXCEEDED	There size quota of the heap was exceeded.
E_OUTOFMEMORY	There was not enough memory available to deserialize the header.
E_INVALIDARG	One or more of the parameters are incorrect.
Other Errors	This function may return other errors not listed above.

Remarks

A message may contain additional transport-specific information that is not part of the message envelope. This transport-specific information can be exposed programmatically as headers of the Message object. This function is used to read a header that has been mapped by a transport into the message.

When using the HTTP channel, the required mappings must be specified before headers can be extracted with this function. For more information, see WS_HTTP_MESSAGE_MAPPING.

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
Library	WebServices.lib
DLL	WebServices.dll

Community Additions

ADD