Carbon


KCFindInternetPasswordWithPath

Header: Keychain.h Carbon status: Under Evaluation

Finds the first Internet password in the default keychain that matches the specified parameters, including path information.

OSStatus KCFindInternetPasswordWithPath (
    StringPtr serverName, 
    StringPtr securityDomain, 
    StringPtr accountName, 
    StringPtr path, 
    UInt16 port, 
    OSType protocol, 
    OSType authType, 
    UInt32 maxLength, 
    void *passwordData, 
    UInt32 *actualLength, 
    KCItemRef *item
);
Parameter descriptions
serverName

A pointer to a Pascal string containing the server name. Pass NULL to match any server name.

securityDomain

A pointer to a Pascal string containing the security domain. Pass NULL to match any domain.

accountName

A pointer to a Pascal string containing the account name. Pass NULL to match any 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 match 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 match 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 match any authentication scheme.

maxLength

The length of the buffer pointed to by passwordData. Pass 0 if you want to obtain the item reference but not the password data. In this case, you must also pass NULL in the passwordData parameter.

passwordData

A pointer to a buffer which will hold the returned password data. Before calling KCFindInternetPasswordWithPath, allocate enough memory for the buffer to hold the data you want to store. Pass NULL if you want to obtain the item reference but not the password data. In this case, you must also pass 0 in the maxLength parameter. On return, a pointer to the returned password data.

actualLength

On return, the actual length of the password data that was retrieved. If the buffer pointed to by passwordData is smaller than the actual length of the data, KCFindInternetPasswordWithPath returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindInternetPasswordWithPath again.

item

On return, a pointer to a reference to the found 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 was found. The result code errKCItemNotFound indicates that no matching password item was found. The result code errKCBufferTooSmall indicates that your application must allocate a new buffer of sufficient size before calling KCFindInternetPasswordWithPath again.

DISCUSSION

The KCFindInternetPasswordWithPath function finds the first Internet password item which matches the attributes you provide, including path information. The buffer specified in the passwordData parameter must be large enough to hold the password data, otherwise KCFindInternetPasswordWithPath returns the result code errKCBufferTooSmall. In this case, your application must allocate a new buffer of sufficient size before calling KCFindInternetPasswordWithPath again. KCFindInternetPasswordWithPath optionally returns a reference to the found item.

KCFindInternetPasswordWithPath 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 kcfindinternetpasswordwithpath to find the first Internet password item matching specified attributes. kcfindinternetpasswordwithpath 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 kcfindinternetpassword function provides the same functionality as KCFindInternetPassword, except that it accepts C strings rather than Pascal strings as arguments. In Keychain 2.0, you should use KCFindInternetPassword, since kcfindinternetpassword 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)