Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

This function provides a method to query the Authentication Reset Component for values.

Syntax 

LONG AuthResetGetValue(
	DWORD dwValueId,
  PVOID pInData,
  DWORD cbInData,
  PVOID pOutBuffer,
  DWORD* pcbOutBuffer
);

Parameters

dwValueId

[in] The value to query.

pInData

[in] Optional pointer to input data. The type and meaning of this data depends on dwValueId. May be NULL.

cbInData

[in] Size of the input data in bytes. Ignored if pInData is NULL.

pOutBuffer

[out] Pointer to a buffer that receives the value associated with dwValueId. The type and meaning of this buffer depend on dwValueId.

If pOutBuffer is NULL, this function returns ERROR_SUCCESS and stores the size of the value, in bytes, in the variable pointed to by pcbOutBuffer. This enables an application to determine the best way to allocate a buffer for the value's data.

pcbOutBuffer

[in, out] Pointer to a variable that specifies the size of the buffer pointed to by the pOutBuffer parameter, in bytes. When the function returns, this variable contains the size of the data copied to pOutBuffer, including any terminating null characters.

If the buffer specified in pOutBuffer is not large enough to hold the data, the function returns ERROR_MORE_DATA and stores the required buffer size in the variable pointed to by pcbOutBuffer. In this case, the contents of pOutBuffer are undefined.

The following table shows the dwValueIdvalues that can be queried.

dwValueId Description pInData pOutBuffer

AUTHRESET_VALUE_

FAILURE_THRESHOLD

Returns the AuthReset failure threshold. This is the number of times that AuthReset may be attempted without succeeding. When this threshold has been reached, AuthResetRequest() will always fail. Returns 0 if no threshold is set.

Ignored

Pointer to a DWORD

AUTHRESET_VALUE_

FAILURE_COUNT

Returns the number of AuthReset failures. Returns 0 if there have been no failures.

Ignored

Pointer to a DWORD

AUTHRESET_VALUE_

SETUP_MESSAGE

Returns the setup message from the registered Authentication Reset Component. In some cases, this message may be overridden or augmented by the IT administrator. If the component does not provide a setup message, pOutBuffer will be an empty string.

This message introduces the Authentication Reset setup process and alerts the user to any requirements (e.g., existing ActiveSync partnership, network connectivity, etc.).

Ignored

String pointer. May be an empty string.

AUTHRESET_VALUE_

SETUPRESULT_

MESSAGE

Returns the result message from the registered Authentication Reset Component. In some cases, this message may be overridden or augmented by the IT administrator. If the component does not provide a result message, pOutBuffer will be an empty string.

HRESULT from AuthReset

Setup()

String pointer. May be an empty string.

AUTHRESET_VALUE_

REQUEST_MESSAGE

Returns the reset message from the registered Authentication Reset Component. In some cases, this message may be overridden or augmented by the IT administrator. If the component does not provide a reset message, pOutBuffer will be an empty string.

This message introduces the Authentication Reset process and alerts the user to any requirements (e.g., existing ActiveSync partnership, network connectivity, etc.).

Ignored

String pointer. May be an empty string.

AUTHRESET_VALUE_

REQUESTRESULT_

MESSAGE

Returns the result message from the registered Authentication Reset Component. In some cases, this message may be overridden or augmented by the IT administrator. If the component does not provide a result message, pOutBuffer will be an empty string.

HRESULT from AuthReset Request()

String pointer. May be an empty string.

Annotated Function Declaration

LONG AuthResetGetValue(DWORD dwValueId, __in_bcount_opt(cbInData) PVOID pInData, DWORD cbInData, __out_bcount_part_opt(*pcbOutBuffer, *pcbOutBuffer) PVOID pOutBuffer, __inout DWORD* pcbOutBuffer);

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in Winerror.h. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error. The following table shows the most common error codes:

ERROR_INVALID_PARAMETER

One of the parameters contains an invalid value. pInData may be the wrong size for the data input required by dwValueId.

ERROR_MORE_DATA

The buffer specified by the pOutbuffer parameter is not large enough to hold the returned data.

ERROR_UNKNOWN_PROPERTY

The dwValueId parameter is not a valid option.

ERROR_UNSUPPORTED

Device configuration does not permit Authentication Reset.

ERROR_INVALID_DATA

The request could not be fulfilled because the underlying data are missing or invalid.

Remarks

Authentication Reset Components may expose additional values for use by specific LAPs (especially in the case that the LAP and Authentication Reset Components are developed by the same party). If the system does not recognize the value in dwValueId, it passes it into the Authentication Reset Component.

The default Windows Mobile Authentication Reset Component attempts to load strings from the registry. This allows IT administrators to override the default messages provided. Other Authentication Reset Components may provide similar functionality.

Requirements

Header aygshell.h
Library Aygshell.dll
Windows Mobile Windows Mobile 6 Classic and later, Windows Mobile 6 Professional and later, Windows Mobile 6 Standard and later

See Also