SFChooseIdentityPanel Class Reference

Inherits from
NSPanel : NSWindow : NSResponder : NSObject
Conforms to
NSUserInterfaceValidations (NSWindow)
NSAnimatablePropertyContainer (NSWindow)
NSUserInterfaceItemIdentification (NSWindow)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/SecurityInterface.framework
Availability
Available in OS X v10.3 and later
Companion guide
Certificate, Key, and Trust Services Programming Guide
Declared in
SFChooseIdentityPanel.h

Overview

The SFChooseIdentityPanel class displays a sheet or panel containing a list of identities and allows a user to select an identity from the list.

An identity is a digital certificate together with its associated private key. This class also allows the user to display the contents of any certificate in the list.

The following figure shows an example of a choose identity panel.

Figure 1  Choose identity panel
Choose identity panel

Tasks

Returning a Shared Certificate Panel Object

Providing Help

Customizing the Appearance of the Sheet or Panel

Displaying a Sheet or Panel

Getting Identity Information from a Sheet or Panel

Working with Domains

Delegate Methods for Providing Help

Class Methods

sharedChooseIdentityPanel

Returns a shared choose identity panel object. If the object has not already been created, this method allocates and initializes the object first.

+ (SFChooseIdentityPanel *)sharedChooseIdentityPanel
Discussion

Use this method if your application displays a single choose identity panel or sheet at a time. If your application can display multiple choose identity panels or sheets at once, you must allocate separate object instances (using the alloc class method inherited from NSObject) and initialize them (using the init instance method, also inherited from NSObject) instead of using this class method.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFChooseIdentityPanel.h

Instance Methods

beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:identities:message:

Displays a list of identities in a modal sheet from which the user can select an identity.

- (void)beginSheetForWindow:(NSWindow *)docWindow modalDelegate:(id)delegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo identities:(NSArray *)identities message:(NSString *)message
Parameters
docWindow

The parent window to which the sheet is attached.

delegate

The delegate object in which the method specified in the didEndSelector parameter is implemented.

didEndSelector

A method selector for a delegate method called when the sheet has been dismissed. Implementation of this delegate method is optional.

contextInfo

A pointer to data that is passed to the delegate method. You can use this data pointer for any purpose you wish.

identities

An array of identity objects (objects of type SecIdentityRef). Use the SecIdentitySearchCopyNext function (in Security/SecIdentitySearch.h) to find identity objects.

message

A message string to display in the sheet.

Discussion

Use the identity method to obtain the identity chosen by the user.

The delegate method has the following signature:

-(void)createPanelDidEnd:(NSWindow *)sheet
       returnCode:(int)returnCode
       contextInfo:(void *)contextInfo

The parameters for the delegate method are:

sheet

The window to which the sheet was attached.

returnCode

The result code indicating which button the user clicked: either NSFileHandlingPanelOKButton or NSFileHandlingPanelCancelButton.

contextInfo

Client-defined contextual data that is passed in the contextInfo parameter of the beginSheetForWindow:... method.

The sheet is dismissed on return from the beginSheetForWindow:... method.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFChooseIdentityPanel.h

domain

Returns the domain that will be associated with the chosen identity.

- (NSString *)domain
Availability
  • Available in OS X v10.5 and later.
Declared In
SFChooseIdentityPanel.h

helpAnchor

Returns the current help anchor string for the sheet or panel.

- (NSString *)helpAnchor
Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

identity

Returns the identity that the user chose in the panel or sheet.

- (SecIdentityRef)identity
Availability
  • Available in OS X v10.3 and later.
Declared In
SFChooseIdentityPanel.h

informativeText

Returns the informative text currently displayed in the panel.

- (NSString *)informativeText
Availability
  • Available in OS X v10.5 and later.
Declared In
SFChooseIdentityPanel.h

policies

Returns an array of policies used to evaluate the status of the displayed certificates.

- (NSArray *)policies
Discussion

This method returns an autoreleased NSArray containing one or more objects of type SecPolicyRef , as set by a previous setPolicies: call, or the Apple X.509 Basic Policy if setPolicies: has not been called. See “AppleX509TP Trust Policies” in Certificate, Key, and Trust Services Reference for a list of policies and object identifiers provided by the AppleX509TP module.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

runModalForIdentities:message:

Displays a list of identities in a modal panel.

- (NSInteger)runModalForIdentities:(NSArray *)identities message:(NSString *)message
Parameters
identities

An array of identity objects (objects of type SecIdentityRef. Use the SecIdentitySearchCopyNext function (in Security/SecIdentitySearch.h) to find identity objects.

message

A message string to display in the panel.

Discussion

This method returns NSOKButton if the default button is clicked, or NSCancelButton if the alternate button is clicked.

Use the identity method to obtain the identity chosen by the user.

Availability
  • Available in OS X v10.3 and later.
See Also
Declared In
SFChooseIdentityPanel.h

setAlternateButtonTitle:

Customizes the title of the alternate button.

- (void)setAlternateButtonTitle:(NSString *)title
Parameters
title

The new title for the alternate button. If this method is not called, or if title is set to nil, the button is not shown.

Discussion

The alternate button is typically labelled “Cancel”. The alternate button dismisses the sheet or panel and returns a value of NSCancelButton.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

setDefaultButtonTitle:

Customizes the title of the default button.

- (void)setDefaultButtonTitle:(NSString *)title
Parameters
title

The new title for the default button. The default title for this button is “OK”.

Discussion

The default button dismisses the sheet or panel and returns a value of NSOKButton.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

setDomain:

Sets an optional domain in which the identity is to be used.

- (void)setDomain:(NSString *)domainString
Parameters
domainString

A string containing a hostname, RFC 822 name (email address), URL, or similar identifier.

Discussion

Call this method to associate a domain with the chosen identity. If the user chooses an identity and a domain is set, an identity preference item is created in the default keychain. Subsequent calls to SecIdentitySearchCreate and SecIdentitySearchCopyNext return the preferred identity for this domain first.

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

setHelpAnchor:

Sets the help anchor string for the sheet or modal panel.

- (void)setHelpAnchor:(NSString *)anchor
Parameters
anchor

The new help anchor string.

Discussion

You may call this function to set a help anchor string if you display a help button in the sheet or modal panel and do not implement the delegate method certificatePanelShowHelp:, or if the delegate method returns NO. If you display a help button, do not set a help anchor string, and do not implement a delegate, the certificate panel displays a default help page (“What is a digital identity?”).

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

setInformativeText:

Sets the optional informative text displayed in the panel.

- (void)setInformativeText:(NSString *)informativeText
Parameters
informativeText

A string containing a hostname, RFC 822 name (email address), URL, or similar identifier.

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

setPolicies:

Specifies one or more policies that apply to the displayed certificates.

- (void)setPolicies:(id)policies
Parameters
policies

The policies to use when evaluating the certificates’ status. You can pass either a SecPolicyRef object or an NSArray (containing one or more SecPolicyRef instances) in this parameter. If policies is set to nil, the Apple X.509 Basic Policy is used.

Discussion

The SFChooseIdentityPanel class evaluates trust for the certificates it displays. Applications typically display certificates in the context of a specific use, such as SSL or S/MIME. You should set only the policy references that apply to your intended use. See “AppleX509TP Trust Policies” for a list of policies and object identifiers provided by the AppleX509TP module.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

setShowsHelp:

Displays a Help button in the sheet or panel.

- (void)setShowsHelp:(BOOL)showsHelp
Parameters
showsHelp

Set to YES to display the help button. The help button is hidden by default.

Discussion

When a user clicks the help button, the choose identity panel first checks the delegate for a certificatePanelShowHelp: method. If the delegate does not implement such a method, or the delegate method returns NO, then the NSHelpManager method openHelpAnchor:inBook: is called with a nil book and the anchor specified by the setHelpAnchor: method. An exception is raised if the delegate returns NO and there is no help anchor set.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

showsHelp

Indicates whether the help button is currently set to be displayed.

- (BOOL)showsHelp
Discussion

This method returns YES if the help button is currently set to be displayed.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h

Delegate Methods

chooseIdentityPanelShowHelp:

Implements custom help behavior for the modal panel.

- (BOOL)chooseIdentityPanelShowHelp:(SFChooseIdentityPanel *)sender
Parameters
sender

The choose identity panel for which to implement custom help.

Discussion

You can use this delegate method to implement custom help if you call the setShowsHelp: method to display a help button in the sheet or panel. If you are not implementing custom help, do not implement this method.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
SFChooseIdentityPanel.h


© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)

Did this document help you? Yes It's good, but... Not helpful...