Contents

RequestInterrupt

Requests the authorization engine to interrupt the currently active authorization mechanism.

Declaration

int (*)(struct __OpaqueAuthorizationEngine *) RequestInterrupt;

Parameters

  • inEngine:

    An opaque handle that is passed to your plug-in when the authorization engine calls your Mechanismcreate function.

Return Value

A result code. Possible results are errAuthorizationSuccess (no error) and errAuthorizationInternal (Security Server internal error).

Discussion

When you call this function, the security engine calls the MechanismDeactivate function for your plug-in’s currently-active mechanism; that is, the mechanism that was last invoked and that has not yet called the SetResult function to report its result. Your mechanism should then stop any active processing and call the DidDeactivate function. When all mechanisms are inactive (that is, they have called either SetResult or DidDeactivate), the authorization engine calls the MechanismInvoke function for the mechanism that called RequestInterrupt so that it can resume the authorization process from that point. After all mechanisms have called SetResult, the authorization engine calls each mechanism’s MechanismDestroy function.

If your mechanism spins off a separate process or UI thread, that thread can call the RequestInterrupt function to re-invoke the mechanism, even if that mechanism has already called the SetResult function. For example, if your plug-in implements a smart card authentication method, reading and evaluating the card might take several minutes to perform. Therefore, in order to avoid blocking other processing while the card is being evaluated, you might spin off a UI thread to interact with the user and then return from MechanismInvoke. When the card has been read, the UI thread calls the SetResult function with a value of kAuthorizationResultAllow and changes the UI to request the user’s PIN. The authorization engine calls the next mechanism, which verifies the PIN. If the user pulls out the card before the verification is complete, the UI thread can call RequestInterrupt. The authorization engine then calls the active mechanism’s MechanismDeactivate function, causing it to terminate the PIN verification and call DidDeactivate. Then the authorization engine calls your UI mechanism’s MechanismInvoke function again. Your UI can then prompt the user to reinsert the card.

To understand this sequence better, suppose your plug-in contains three mechanisms: A, B, and C. Mechanism A has called SetResult and has no active processes. Mechanism B has called SetResult, but still has a UI thread running. Mechanism C is running and has not yet called SetResult. The user clicks Cancel or otherwise interrupts the UI thread, causing the UI thread to call the RequestInterrupt function. The following sequence of events occurs:

  1. The authorization engine calls mechanism C’s MechanismDeactivate function.

  2. Mechanism C stops active processing and calls the DidDeactivate function.

  3. The authorization engine calls mechanism B’s MechanismInvoke function (because mechanism B is the one that called RequestInterrupt).

  4. Mechanism B updates the UI and calls the SetResult function with the value kAuthorizationResultAllow.

  5. The authorization engine calls mechanism C’s MechanismInvoke function.

  6. Mechanism C completes processing and calls SetResult with kAuthorizationResultAllow.

  7. The authorization engine calls the MechanismDestroy function of each mechanism in turn (A, B, then C).

The authorization engine sends you the entry point to the RequestInterrupt function in an AuthorizationCallbacks structure when you call the AuthorizationPluginCreate function.