Mac Developer Library

Developer

SecurityInterface Framework Reference SFChooseIdentityPanel Class Reference

Options
Deployment Target:

On This Page
Language:

SFChooseIdentityPanel

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

Inheritance


Import Statement


Not Applicable @import SecurityInterface;

Availability


Available in OS X v10.3 and later
  • Returns a shared choose identity panel object. If the object has not already been created, this method allocates and initializes the object first.

    Declaration

    Objective-C

    + (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.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    See Also

    +alloc(NSObject)
    -init(NSObject)

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

    Declaration

    Objective-C

    - (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 NOfalse. 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?”).

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Displays a Help button in the sheet or panel.

    Declaration

    Objective-C

    - (void)setShowsHelp:(BOOL)showsHelp

    Parameters

    showsHelp

    Set to YEStrue 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 NOfalse, 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 NOfalse and there is no help anchor set.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

    - (NSString *)helpAnchor

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

    - (BOOL)showsHelp

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Customizes the title of the alternate button.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Customizes the title of the default button.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Objective-C

    - (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 in Certificate, Key, and Trust Services Reference for a list of policies and object identifiers provided by the AppleX509TP module.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

    See Also

    – policies

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

    Declaration

    Objective-C

    - (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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Returns the informative text currently displayed in the panel.

    Declaration

    Objective-C

    - (NSString *)informativeText

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • Sets the optional informative text displayed in the panel.

    Declaration

    Objective-C

    - (void)setInformativeText:(NSString *)informativeText

    Parameters

    informativeText

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

    Import Statement

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (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.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

  • Displays a list of identities in a modal panel.

    Declaration

    Objective-C

    - (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.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    - (SecIdentityRef)identity

    Import Statement

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    - (NSString *)domain

    Import Statement

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (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.

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • Implements custom help behavior for the modal panel.

    Objective-C

    - (BOOL)chooseIdentityPanelShowHelp:(SFChooseIdentityPanel *)sender

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setShowsHelp:
    -setDelegate: (NSWindow)