WsGetSecurityTokenProperty function (webservices.h)

Extracts a field or a property from a security token. If the queried property does not use the heap parameter, the returned data is owned by the security token and remains valid as long as the security token itself remains valid. Specifically, for security tokens extracted from a received message, the security token and fields extracted from it are valid only as long as the message is not reset or freed.

If the heap parameter is required by the property, then the returned data is stored on the heap, with its lifetime detached from the underlying token.

Syntax

HRESULT WsGetSecurityTokenProperty(
  [in]           WS_SECURITY_TOKEN             *securityToken,
  [in]           WS_SECURITY_TOKEN_PROPERTY_ID id,
                 void                          *value,
  [in]           ULONG                         valueSize,
  [in, optional] WS_HEAP                       *heap,
  [in, optional] WS_ERROR                      *error
);

Parameters

[in] securityToken

The security token from which the property should be extracted.

[in] id

The id of the property to retrieve.

value

The location to store the retrieved property. The pointer must have an alignment compatible with the type of the property.

[in] valueSize

The number of bytes allocated by the caller to store the retrieved property.

[in, optional] heap

Heap to store additional property data. This parameter must be non-NULL when the queried property is WS_SECURITY_TOKEN_PROPERTY_SYMMETRIC_KEY and must be NULL otherwise.

[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.

Requirements