SetAPIErrorHandler (Compact 2013)

3/28/2014

This function registers an error handler for a Program Static Library (PSL). The error handler, PFNAPIERRHANDLER, is called when the caller tries to call an API within the API set designated by hApiSet with invalid arguments.

Syntax

BOOL SetAPIErrorHandler(
  HANDLE hApiSet,
  PFNAPIERRHANDLER pfnHandler
);

Parameters

• hApiSet
  [in] Handle to an API set returned from the call to the CreateAPISet function.

• pfnHandler
  [in] Prototype of the error handler, shown by the following code example:

  typedef DWORD (*PFNAPIERRHANDLER)(DWORD);
  

  The parameter to the PSL error handler is the index of the API called by the user that failed validation. The return value from the PSL error handler is passed back to the caller as if it were the return value from the API call. If a PSL does not register any error handler for its API set, the kernel raises an exception whenever parameter validation for an API belonging to that PSL fails.

  The function specified by this parameter should be called whenever parameter validation fails for any of the API calls in the API set declared in the call to CreateAPISet.

Return Value

The error value to be passed back to the caller.

Remarks

This API provides a mechanism for PSL servers to register an API as a common parameter error handler for the API set. The kernel does basic validation of first level parameters on every API call. If this validation fails and there is a registered error handler for that API, the kernel calls the PSL error handler with the index to the API that failed the validation. The PSL server can determine what return value to send to the caller when the parameter validation fails.

In general, PSL error handlers should do the following:

1. Set the last error value to an appropriate error code.
2. Return a value to the kernel so that the kernel can pass this value back to the caller as the return value for the original API.

Requirements

See Also

Reference

Kernel Functions
CreateAPISet
WaitForAPIReady