WsAddMappedHeader function (webservices.h)

Article
02/22/2024

Adds a specified mapped header to the message.

Syntax

HRESULT WsAddMappedHeader(
  [in]           WS_MESSAGE          *message,
  [in]           const WS_XML_STRING *headerName,
  [in]           WS_TYPE             valueType,
  [in]           WS_WRITE_OPTION     writeOption,
  [in]           const void          *value,
  [in]           ULONG               valueSize,
  [in, optional] WS_ERROR            *error
);

Parameters

[in] message

Pointer to a WS_MESSAGE structure representing the message to which to add the mapped header.

The message can be in any state except WS_MESSAGE_STATE_EMPTY (see the WS_MESSAGE_STATE enumeration.

[in] headerName

Pointer to a WS_XML_STRING containing the name of the header.

[in] valueType

The type of header value to deserialize. For possible types and the corresponding headers, see the WS_HEADER_TYPE

[in] writeOption

Whether the header is required, and how the value is allocated. For more information, see the WS_WRITE_OPTION enumeration.

[in] value

The header value to serialize. For more information, see the WS_WRITE_OPTION enumeration.

[in] valueSize

The size of the value being serialized, in bytes.

[in, optional] error

Pointer to a WS_ERROR structure that receives additional error information if the function fails.

Return value

If the function succeeds, it returns NO_ERROR; otherwise, it returns an HRESULT error code.

Return code	Description
E_OUTOFMEMORY	Insufficient memory to complete the operation.
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. The WsAddMappedHeader function is used to add such a header that will be mapped into some transport-specific location.

When you use the HTTP channel, you must specify the required mappings before before you call this function to add the headers. For more information, see WS_HTTP_MESSAGE_MAPPING.

If you are replacing a header, call the WsRemoveMappedHeader function to remove the existing instances of the header before you call WsAddMappedHeader.

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