Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

SFCertificatePanel Class Reference

Overview

The SFCertificatePanel class displays one or more certificates in a panel or sheet. It can optionally display all of the certificates in a certificate chain.

The following figure shows an example of a certificate panel.

Figure 1  Certificate panel

This class displays certificate details, but not trust settings. To display a certificate with editable trust settings in a panel or sheet, use the SFCertificateTrustPanel class (SFCertificateTrustPanel). To display certificates in a custom view, use the SFCertificateView class (SFCertificateView).

Note that for Mac OS X v10.4 and later, this class displays the evaluation status for each certificate. You can modify how the certificates are evaluated by calling the setPolicies: method.

Tasks

Returning a Shared Certificate Panel Object

• + sharedCertificatePanel

Providing Help

• – setHelpAnchor:
• – setShowsHelp:
• – helpAnchor
• – showsHelp

Customizing the Appearance of the Sheet or Panel

• – setAlternateButtonTitle:
• – setDefaultButtonTitle:
• – setPolicies:
• – policies

Displaying a Sheet or Panel

• – beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:certificates:showGroup:
• – runModalForCertificates:showGroup:

Providing help

• – certificatePanelShowHelp:  delegate method

Class Methods

sharedCertificatePanel

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

+ (SFCertificatePanel *)sharedCertificatePanel

Discussion

Use this method if your application displays a single certificate panel or sheet at a time. If your application can display multiple certificate 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 Mac OS X v10.3 and later.

See Also

• +alloc (NSObject)
• -init (NSObject)

Declared In

Instance Methods

beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:certificates:showGroup:

Displays one or more certificates in a modal sheet.

- (void)beginSheetForWindow:(NSWindow *)docWindow modalDelegate:(id)delegate didEndSelector:(SEL)didEndSelector contextInfo:(void *)contextInfo certificates:(NSArray *)certificates showGroup:(BOOL)showGroup

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.

certificates

The certificates to display. Pass an NSArray containing one or more objects of type SecCertificateRef in this parameter. The first certificate in the array must be the leaf certificate. The other certificates (if any) can be included in any order.

showGroup

Specifies whether additional certificates (other than the leaf certificate) are displayed.

Discussion

The behavior of this method is somewhat different in Mac OS X v10.4 and later versus Mac OS X v10.3. In Mac OS X v10.3, the sheet displays whatever certificates you pass in the certificates parameter (provided the showGroup parameter is set to YES). Starting with Mac OS X v10.4, the sheet displays the leaf certificate (that is, the first certificate in the array you pass) plus any other certificates in the certificate chain that the Security Server can find. If you include all of the certificates in the chain in the certificates parameter, you can ensure that the same certificates are displayed whatever the version of the operating system, and may decrease the time required to find and display the certificates in Mac OS X v10.4 and later.

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 beginSheetForDirectory:... method.

The delegate method may dismiss the keychain settings sheet itself; if it does not, the sheet is dismissed on return from the beginSheetForDirectory:... method.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – runModalForCertificates:showGroup:

Declared In

helpAnchor

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

- (NSString *)helpAnchor

Availability

• Mac OS X v10.4

See Also

• – setHelpAnchor:

Declared In

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

• Mac OS X v10.4

See Also

• – setPolicies:

Declared In

runModalForCertificates:showGroup:

Displays one or more specified certificates in a modal panel.

- (NSInt)runModalForCertificates:(NSArray *)certificates showGroup:(BOOL)showGroup

Parameters

certificates

The certificates to display. Pass an NSArray containing one or more objects of type SecCertificateRef in this parameter. The first certificate in the array must be the leaf certificate. The other certificates (if any) can be included in any order.

showGroup

Specifies whether additional certificates (other than the leaf certificate) are displayed. To show only a single certificate, specify only one SecCertificateRef in the array and set showGroup to NO.

Discussion

This method returns the integer constant NSOKButton when dismissed.

The behavior of this method is somewhat different in Mac OS X v10.4 and later versus Mac OS X v10.3. In Mac OS X v10.3, the panel displays whatever certificates you pass in the certificates parameter (provided the showGroup parameter is set to YES). Starting with Mac OS X v10.4, the panel displays the leaf certificate (that is, the first certificate in the array you pass) plus any other certificates in the certificate chain that the Security Server can find. If you include all of the certificates in the chain in the certificates parameter, you can ensure that the same certificates are displayed whatever the version of the operating system, and may decrease the time required to find and display the certificates in Mac OS X v10.4 and later.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – beginSheetForWindow:modalDelegate:didEndSelector:contextInfo:certificates:showGroup:

Declared In

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

• Mac OS X v10.4

See Also

• – setDefaultButtonTitle:
• – runModalForTrust:message:

Declared In

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

• Mac OS X v10.4

See Also

• – setAlternateButtonTitle:

Declared In

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 (“Why isn’t a certificate being accepted?”).

Availability

• Mac OS X v10.4

See Also

• – setShowsHelp:
• – certificatePanelShowHelp:
• – helpAnchor

Declared In

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

Applications typically display a certificate panel 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

• Mac OS X v10.4

See Also

• – policies

Declared In

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 certificate 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

• Mac OS X v10.4

See Also

• – certificatePanelShowHelp:
• – setHelpAnchor:
• -openHelpAnchor:inBook:(NSHelpManager)
• – showsHelp

Declared In

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

• Mac OS X v10.4

See Also

• – setShowsHelp:

Declared In

Delegate Methods

certificatePanelShowHelp:

Implements custom help behavior for the modal panel.

- (BOOL)certificatePanelShowHelp:(SFCertificatePanel *)sender

Parameters

sender

The certificate 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

• Mac OS X v10.4

See Also

• – setShowsHelp:
• -setDelegate: (NSWindow)

Declared In

Next Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice