WsGetMappedHeader function (webservices.h)

Article
10/13/2021

Finds a mapped header in the message and deserializes it.

Syntax

HRESULT 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, optional] WS_HEAP                    *heap,
                 void                       *value,
  [in]           ULONG                      valueSize,
  [in, optional] WS_ERROR                   *error
);

Parameters

[in] message

The message containing the header.

The message can be in any state but WS_MESSAGE_STATE_EMPTY.

[in] headerName

The name of the mapped header.

[in] repeatingOption

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.

[in] headerIndex

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

[in] valueType

The type of value to deserialize.

[in] readOption

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.

[in, optional] heap

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.

[in] valueSize

The interpretation of this parameter depends on the WS_READ_OPTION.

[in, optional] error

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	The 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

Requirement	Value
Minimum supported client	Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	webservices.h
Library	WebServices.lib
DLL	WebServices.dll

Share via