SFAuthorizationPluginView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/SecurityInterface.framework
Availability
Available in OS X v10.5 and later
Companion guide
Declared in
SFAuthorizationPluginView.h
Related sample code

Overview

The SFAuthorizationPluginView class allows authorization plug-in developers to create a custom view their plug-in can display.

If you’re developing an authorization plug-in, you can subclass the SFAuthorizationPluginView class to create views that provide a custom user interface for your plug-in. By subclassing the SFAuthorizationPluginView class, you avoid changing or duplicating the Apple-provided authentication or login window dialogs to display your custom view.

To instantiate your SFAuthorizationPluginView subclass, you need the callbacks structure containing entry points to the Security Server that you receive in your plug-in’s AuthorizationPluginCreate function and the authorization engine handle you receive in your plug-in’s MechanismCreate function.

Your custom subclass of SFAuthorizationPluginView must override the following methods:

Tasks

Initializing an SFAuthorizationPluginView Object

Getting Instance Information

Responding to User Actions

Configuring the User Interface

Setting Up the Keyboard Loop

Enabling and Disabling Controls

Communicating with the Authorization Plug-in

Instance Methods

buttonPressed:

Informs the SFAuthorizationPluginView instance when a user presses a button in the custom view.

- (void)buttonPressed:(SFButtonType)inButtonType
Parameters
inButtonType

The type of button that was pressed.

Discussion

By default, buttonPressed: will set a result of Deny when the OK or Login buttons are pressed. An SFAuthorizationPluginView subclass needs to override this method to set the context values for the short name of the user so that user attributes can be looked up. To do this, use kAuthorizationEnvironmentUsername as the key. A subclass should also set any additional context values that are needed by the authorization plug-in to verify the user’s credentials. To do this, use the appropriate function pointers you receive from callbacks.

When you override this method, do not call [super buttonPressed].

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

callbacks

Returns the AuthorizationCallbacks structure with which this instance was initialized.

- (const AuthorizationCallbacks *)callbacks
Return Value

An object of type AuthorizationCallbacks.

Discussion

Use the AuthorizationCallbacks structure to get the function pointers to functions such as SetResult and SetContextValue.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

didActivate

Informs the SFAuthorizationPluginView instance when the authorization plug-in makes the instance’s user interface active.

- (void)didActivate
Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

didDeactivate

Informs the SFAuthorizationPluginView instance when the authorization plug-in deactivates its user interface.

- (void)didDeactivate
Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

displayView

Displays the user interface provided by the SFAuthorizationPluginView subclass.

- (void)displayView
Discussion

It’s not likely that you will want to override this method, but if you do, be sure to call [super displayView]. If you don’t call [super displayView], your custom view will not get displayed.

This method will raise an SFDisplayViewException exception if an error occurs while displaying the authorization dialog.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

engineRef

Returns the authorization engine handle with which this instance was initialized.

Return Value

A handle of type AuthorizationEngineRef.

Discussion

Use the authorization engine handle when you call the functions in the AuthorizationCallbacks structure to set a result or a context value.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
SFAuthorizationPluginView.h

firstKeyView

Returns the first view in the keyboard loop of the view.

- (NSView *)firstKeyView
Discussion

The default return value of this method is nil. When the authorization plug-in calls this method, your subclass should return the first view in the keyboard loop of your custom NSView object.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
SFAuthorizationPluginView.h

firstResponder

Returns the view that should get focus for keyboard events.

- (NSResponder *)firstResponder
Discussion

The default return value of this method is nil. When the authorization plug-in calls this method, your subclass should return the view that should get the focus for keyboard events.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

initWithCallbacks:andEngineRef:

Returns an SFAuthorizationPluginView object with the specified callbacks and authorization engine handle.

- (id)initWithCallbacks:(const AuthorizationCallbacks *)callbacks andEngineRef:(AuthorizationEngineRef)engineRef
Parameters
callbacks

The structure of type AuthorizationCallbacks provided to the authorization plug-in in its AuthorizationPluginCreate function.

engineRef

The handle of type AuthorizationEngineRef provided to the authorization plug-in in its MechanismCreate function.

Return Value

An initialized SFAuthorizationPluginView instance.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
SFAuthorizationPluginView.h

lastError

Returns the last error that occurred during evaluation.

- (NSError *)lastError
Discussion

Your authorization plug-in should override this method and return the last error that occurred during evaluation or nil if no error occurred.

A downstream plug-in can set a context value using the kAuthorizationContextFlagSticky flag to make it available to the SFAuthorizationPluginView class in case of an error.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

lastKeyView

Returns the last view in the keyboard loop of the view.

- (NSView *)lastKeyView
Discussion

The default return value of this method is nil. When the authorization plug-in calls this method, your subclass should return the last view in the keyboard loop of your custom NSView object.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
SFAuthorizationPluginView.h

setButton:enabled:

Enables or disables a button in the SFAuthorizationPluginView instance’s user interface.

- (void)setButton:(SFButtonType)inButtonType enabled:(BOOL)inEnabled
Parameters
inButtonType

The type of the button.

inEnabled

YES to enable the button, NO to disable the button.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

setEnabled:

Enables or disables the controls in the SFAuthorizationPluginView instance’s view.

- (void)setEnabled:(BOOL)inEnabled
Parameters
inEnabled

The state the controls should be in.

Discussion

When the authorization plug-in calls this method, the subclass should call setEnabled: on the controls that are in its view.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

updateView

Tells the authorization plug-in to get and display the appropriate view in the SFAuthorizationPluginView instance’s user interface.

- (void)updateView
Discussion

Your subclass of SFAuthorizationPluginView should call this method when a user clicks a button in your view that should result in a new view being displayed. Calling this method causes the authorization plug-in to get the new view and display it.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

viewForType:

Returns the appropriate NSView object for the specified SFViewType.

- (NSView *)viewForType:(SFViewType)inType
Parameters
inType

The type of view being requested by the authorization plug-in.

Return Value

An NSView object representing either a credentials view or an identity and credentials view.

Discussion

When the authorization plug-in calls this method, the SFAuthorizationPluginView instance should return the NSView object that represents the view indicated by the specified SFViewType. The NSView object and its contents should have the autoresize flags set to allow the view to be resized.

Note that although a maximum width of 394 points is currently supported, this may change in the future. You should not assume that the width of the NSView object will never change.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

willActivateWithUser:

Informs the SFAuthorizationPluginView instance when its user interface is about to be made active by the Apple-provided Security Agent.

- (void)willActivateWithUser:(NSDictionary *)inUserInformation
Parameters
inUserInformation

A dictionary that contains the following information:

  • kSFAuthorizationPluginViewUserNameKey

    An NSString object containing the selected user’s name

  • kSFAuthorizationPluginViewUserShortNameKey

    An NSString object containing the selected user’s short name

Note: inUserInformation may be nil.

Discussion

Your SFAuthorizationPluginView instance can use the user name to pre-populate a text field in the user interface.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

Constants

SFButtonType

These constants define the button types used by authorization plug-ins.

typedef enum{
   SFButtonTypeCancel    = NSCancelButton,
   SFButtonTypeOK        = NSOKButton,
   SFButtonTypeBack      = SFButtonTypeCancel,
   SFButtonTypeLogin     = SFButtonTypeOK
} SFButtonType;
Constants
SFButtonTypeCancel

Indicates the Cancel button was pressed.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.

SFButtonTypeOK

Indicates the OK button was pressed.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.

SFButtonTypeBack

Indicates the Back button was pressed.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.

SFButtonTypeLogin

Indicates the Login button was pressed.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

SFViewType

These constants define the view type requested by the authorization plug-in.

typedef enum {
   SFViewTypeIdentityAndCredentials,
   SFViewTypeCredentials
} SFViewType;
Constants
SFViewTypeIdentityAndCredentials

Indicates a view that contains controls for identity and credentials was requested by the authorization plug-in.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.

SFViewTypeCredentials

Indicates a view that contains controls for credentials was requested by the authorization plug-in.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.

Availability
  • Available in OS X v10.5 and later.
Declared In
SFAuthorizationPluginView.h

Exceptions

Exceptions thrown by the SFAuthorizationPluginView class

extern NSString * const SFDisplayViewException;
Constants
SFDisplayViewException

Raised when an error occurs in displaying the authorization dialog.

Available in OS X v10.5 and later.

Declared in SFAuthorizationPluginView.h.