Carbon


KCAddInternetPasswordWithPath

Header: Keychain.h Carbon status: Under Evaluation

Adds a new Internet server password with a specified path to the default keychain.

OSStatus KCAddInternetPasswordWithPath (
    StringPtr serverName, 
    StringPtr securityDomain, 
    StringPtr accountName, 
    StringPtr path, 
    UInt16 port, 
    OSType protocol, 
    OSType authType, 
    UInt32 passwordLength, 
    const void *passwordData, 
    KCItemRef *item
);
Parameter descriptions
serverName

A pointer to a Pascal string containing the server name.

securityDomain

A pointer to a Pascal string containing the security domain. This parameter is optional, as not all protocols will require it.

accountName

A pointer to a Pascal string containing the account name.

path

A pointer to a Pascal string containing additional information that specifies a file or directory on the server specified by serverName. In a typical URL, path information begins directly after the first slash (“/”) character following the server name. This parameter is optional.

port

The TCP/IP port number. Pass the constant kAnyPort, described in “Default Internet Port Constant”, to specify any port.

protocol

The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values. Pass the constant kAnyProtocol, described in “Default Internet Protocol Constant”, to specify any protocol.

authType

The authentication scheme used. See “Authentication Type Constants” for a description of possible values. Pass the constant kAnyAuthType, described in “Default Internet Authentication Type Constant”, to specify any authentication scheme.

passwordLength

The length of the buffer pointed to by passwordData.

passwordData

A pointer to a buffer which will hold the returned password data. Before calling KCAddInternetPasswordWithPath, allocate enough memory for the buffer to hold the data you want to store.

item

On return, a pointer to a reference to the added item. Pass NULL if you don’t want to obtain this reference.

function result

A result code. The result code errKCNoDefaultKeychain indicates that no default keychain could be found. The result code errKCDuplicateItem indicates that you tried to add a password that already exists in the keychain. The result code errKCDataTooLarge indicates that you tried to add more data than is allowed for a record of this type.

DISCUSSION

The KCAddInternetPasswordWithPath function enables you to specify path information when adding a new Internet server password to the default keychain. Required parameters to identify the password are serviceName and accountName (you cannot pass NULL for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. KCAddInternetPasswordWithPath optionally returns a reference to the newly added item.

KCAddInternetPasswordWithPath will automatically call the function KCUnlock to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

You can also call the function kcaddinternetpasswordwithpath to add a new Internet server password to the default keychain. kcaddinternetpasswordwithpath requires that you pass a pointer to a C string instead of a pointer to a Pascal string for the serverAddress, serverName, volumeName, accountName, and passwordData parameters.

VERSION NOTES

Available beginning with Keychain Manager 2.0. In Keychain Manager 1.0, the kcaddinternetpasswordwithpath function provides the same functionality as KCAddInternetPasswordWithPath, except that it accepts C strings rather than Pascal strings as arguments. In Keychain 2.0, you should use KCAddInternetPasswordWithPath, since kcaddinternetpasswordwithpath is provided for convenience only and may be removed from the header file at some point in the future.


© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)