| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/SecurityInterface.framework |
| Availability | Available in Mac OS X v10.3 and later |
| Companion guide | |
| Declared in | SFChooseIdentityPanel.h |
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.
– beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:identities:message:
– runModalForIdentities:message:
– chooseIdentityPanelShowHelp: delegate method
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
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.
SFChooseIdentityPanel.hDisplays 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
The parent window to which the sheet is attached.
The delegate object in which the method specified in the didEndSelector parameter is implemented.
A method selector for a delegate method called when the sheet has been dismissed. Implementation of this delegate method is optional.
A pointer to data that is passed to the delegate method. You can use this data pointer for any purpose you wish.
An array of identity objects (objects of type SecIdentityRef). Use the SecIdentitySearchCopyNext function (in Security/SecIdentitySearch.h) to find identity objects.
A message string to display in the sheet.
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:
The window to which the sheet was attached.
The result code indicating which button the user clicked: either NSFileHandlingPanelOKButton or NSFileHandlingPanelCancelButton.
Client-defined contextual data that is passed in the contextInfo parameter of the beginSheetForWindow:... method.
The delegate method may dismiss the keychain settings sheet itself; if it does not, the sheet is dismissed on return from the beginSheetForWindow:... method.
SecIdentitySearchCopyNext (Security/SecIdentitySearch.h)– identity– runModalForIdentities:message:SFChooseIdentityPanel.hReturns the current help anchor string for the sheet or panel.
- (NSString *)helpAnchor
SFChooseIdentityPanel.hReturns the identity that the user chose in the panel or sheet.
- (SecIdentityRef)identity
SFChooseIdentityPanel.hReturns an array of policies used to evaluate the status of the displayed certificates.
- (NSArray *)policies
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.
SFChooseIdentityPanel.hDisplays a list of identities in a modal panel.
- (NSInteger)runModalForIdentities:(NSArray *)identities message:(NSString *)message
An array of identity objects (objects of type SecIdentityRef. Use the SecIdentitySearchCopyNext function (in Security/SecIdentitySearch.h) to find identity objects.
A message string to display in the panel.
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.
SecIdentitySearchCopyNext (Security/SecIdentitySearch.h)– identity– beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:identities:message:SFChooseIdentityPanel.hCustomizes the title of the alternate button.
- (void)setAlternateButtonTitle:(NSString *)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.
The alternate button is typically labelled “Cancel”. The alternate button dismisses the sheet or panel and returns a value of NSCancelButton.
SFChooseIdentityPanel.hCustomizes the title of the default button.
- (void)setDefaultButtonTitle:(NSString *)title
The new title for the default button. The default title for this button is “OK”.
The default button dismisses the sheet or panel and returns a value of NSOKButton.
SFChooseIdentityPanel.hSets the help anchor string for the sheet or modal panel.
- (void)setHelpAnchor:(NSString *)anchor
The new help anchor string.
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?”).
SFChooseIdentityPanel.hSpecifies one or more policies that apply to the displayed certificates.
- (void)setPolicies:(id)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.
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.
SFChooseIdentityPanel.hDisplays a Help button in the sheet or panel.
- (void)setShowsHelp:(BOOL)showsHelp
Set to YES to display the help button. The help button is hidden by default.
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.
SFChooseIdentityPanel.hIndicates whether the help button is currently set to be displayed.
- (BOOL)showsHelp
This method returns YES if the help button is currently set to be displayed.
SFChooseIdentityPanel.hImplements custom help behavior for the modal panel.
- (BOOL)chooseIdentityPanelShowHelp:(SFChooseIdentityPanel *)sender
The choose identity panel for which to implement custom help.
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.
– setShowsHelp:-setDelegate: (NSWindow)SFChooseIdentityPanel.hLast updated: 2009-10-14
