-1 or less, you can call a GetLastError appropriate to
the context and retrieve information about the last error. That call may
return NULL which basically means "Unknown Error". Note that in the presence
of threads, the error information may become inaccurate. */
typedef struct _t_SecErrorInfo
{
/** The size of this structure. */
ASSize_t size;
/** The description of the error. */
ASText text;
/** Adobe use only. It must be set to NULL by external developers. */
void* reserved;
}
SecErrorInfoRec, *SecErrorInfo;
/** */
typedef struct _t_DirConnection* DirConnection;
/************************************************************************************
* Rules for out-parameters
***********************************************************************************/
/* Consider the following function prototypes:
void foo(ASBool* outResult);
void bar(void** outResult);
void baz(ASCab outResult);
- if(outResult==0) when the call is made, the caller is not interested in this
out parameter. The callee should not fail just because outResult is 0.
- if(outResult!=0 && *outResult==0) when the call is made, the callee is
expected to allocate the result and the caller is responsible for its
deallocation. One exception to this rule is when the callee wishes to
return an "empty value" (such as an empty ASText or ASCab), it will leave
*outResult==0.
- if(outResult!=0 && *outResult!=0) when the call is made, the callee will
deallocate the *outResult if needed and replace it with a new value.
- Raw memory and primitive structures (the ones that don't have any members that
require deallocation) shall be deallocated with ASFree/miFree. ASCabs ASTexts
and other known types shall be deallocated with their special routines
(ASTextDestroy(), ASCabDestroy(), etc.)
- If a call fails, *outResult remains unchanged.
*/
/************************************************************************************
* Directory Information format
***********************************************************************************/
/** A directory information structure contains configuration settings used to
establish a connection to a directory. Common top-level properties are
defined below. Note that the prefix DirStdEntry_ is reserved for standard
entries and should not be used for entries specific to a particular directory.
Optionally, this could contain other configuration information specific to
the directory.
*/
typedef ASCab DirectoryInfo;
/* The name of this directory for display purposes.
An example of this would be "Adobe Employees".
TEXT, REQUIRED.
*/ #define PROP_DirectoryInfo_Name "dirStdEntryName" /* The ID. It is a unique atom that identifies the directory. An example of this would beAdobe.PPKMS.LDAP.dir0.
ATOM, REQUIRED.
*/ #define PROP_DirectoryInfo_ID "dirStdEntryID" /* The language independent name of the directory handler to be used when connecting to this directory. This is required when there are multiple direcrtory handlers within a DSP. An example of this would beAdobe.PPKMS.ADSI.
ATOM, OPTIONAL.
*/ #define PROP_DirectoryInfo_DirHandlerID "dirStdEntryPrefDirHandlerID" /* The language independent name of the type of directory this represents. This is required when you want to import or export entries. An example of this would beLDAP, ADSI.
ATOM, OPTIONAL.
*/ #define PROP_DirectoryInfo_DirType "dirStdEntryDirType" /* An integer that represent the version of the directory.Integer, OPTIONAL.
*/ #define PROP_DirectoryInfo_Version "dirStdEntryVersion" /************************************************************************************ * Directory Attributes ***********************************************************************************/ /* These are attribute names used in the "standard" connection functions (DirSetStandardOutputOptions(), DirStandardSearch(), etc.) These attribute names are used both as keys/property names (in representation of the search results) and as values (in representation of output settings). The attributes are stored as ASText so as to enable easy conversion from JavaScript. */ #define ATTR_DirFirstName "firstName" #define ATTR_DirLastName "lastName" #define ATTR_DirFullName "fullName" #define ATTR_DirEmail "email" #define ATTR_DirCertificates "certificates" #define ATTR_DirPrefEncryptionCert "defaultEncryptCert" /************************************************************************************ * Connection Interface. ***********************************************************************************/ /** Group names are represented as text in an ASCab. For example:{ ("0", "friends"), ("1", "family"), ... }
kSecOk is successful, kSecError otherwise.
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_getGroups)
( DirConnection inConnection, DirGroupList outGroupList );
/*-----------------------------------------------------------------------------------
The output options of a connection determine which directory attributes will be
returned when a search is performed. There are two calls for setting the output
options, and they differ in the way the attributes are interpreted. The default
behavior for a new connection if output options have not been explicitly set, is
as if DirSetStandardOutputOptions call with all "standard" attributes has been
made.
*/
/** A directory attribute collection is used to set output options of a directory
connection.
The collection is represented in an ASCab as:
{ ("0", "nameOfAttribute1"), ("1", "nameOfAttribute2"), ... }
ATTR_Certificates attribute is intended to encompass all
certificate attributes a directory might have. If ATTR_Certificates is requested,
it may have to be translated into several attributes depending on the directory.
@param inConnection The connection for which the output options are set.
@param inRequestedAttrs Contains only standard attribute names defined as ATTR_
constants above. These names will most likely need to be translated to ones
understood by specific directory types. For example, in the case of a generic LDAP
directory, ATTR_LastName may be interpreted as "sn".
@param outUnsupportedAttrs Used to pass back the the names of attributes (from
inRequestedAttrs) that are not supported by the connection.
@return kOK or kSecError
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_setStandardOutputOptions)
( DirConnection inConnection,
DirAttributes inRequestedAttrs, DirAttributes outUnsupportedAttrs);
/** TBD
@param inConnection The connection for which the output options are set.
@param inRequestedAttrs Contains attribute names that are not translated. Any
attribute names can be used as long as they are supported by the target directory.
@param outUnsupportedAttrs Used to pass back the the names of attributes (from
inRequestedAttrs) that are not supported by the connection.
@return kSecOk or kSecError
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_setCustomOutputOptions)
( DirConnection inConnection,
DirAttributes inRequestedAttrs, DirAttributes outUnsupportedAttrs);
/*-----------------------------------------------------------------------------------
Perform a search using a connection. There are three different search functions,
and although all three are optional, at least one should be implemented for a
connection to be usable.
*/
/** Directory search criteria are represented as a set of key/value pairs where the
keys are attribute names and the values are search strings applied to those
attributes. A logical "AND" is implied when multiple search criteria are present.
Unrecognized search criteria are ignored.
@example { ("firstName", "John"), ("lastName", "S*") } searches for people with
the first name "John" whose last name starts with letter 'S'.
@note Special Case: For a standard search, the value of the ATTR_Certificates search
criterion shall be a list of certificates. In order for a directory entry to
match the criterion, it must have all those certificates.
*/
typedef ASCab DirSearchCriteria;
/** Search and enumeration results are represented as a two-dimensional ASCab where
each "row" is itself an ASCab that contains attributes defined by SetOutputOptions
calls.
@example
{ ("0", { ("fullName", "John Doe"), ("email", "johndoe@yahoo.com") } ),
("1", { ("fullName", "Jane Doe"), ("email", "janedoe@hotmail.com") } ) }
ATTR_Certificates is
included, the ATTR_Certificates value in the row ASCab objects will be another ASCab,
which stores all certificates associated with that directory entry.
@example
{ ("0", { ("fullName", John Doe"), ("certificates", { ("0", encryptionCertBinaryValue), ("1", signingCertBinaryValue) } ) } ) }
*/
typedef ASCab DirResults;
/** TBD
@param inConnection The connection that is used to perform the search.
@param inSearchCriteria Search criteria to be used. The only standard attribute
names defined as ATTR_ constants above are present. These names most likely
will need to be translated to ones understood by specific directory types.
For example, in the case of a generic LDAP directory, ATTR_LastName may be
interpreted as "sn".
@param inGroup Specifies the group, which should be searched. NULL means that all
groups should be searched.
@param outResults Points to the results of the search.
@return kSecOk or kSecError
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_standardSearch)
( DirConnection inConnection,
DirSearchCriteria inSearchCriteria,
ASText inGroup,
DirResults outResults );
/* TBD
@param inConnection The connection that is used to perform the search.
@param inSearchCriteria Search criteria to be used. The attribute names are not
translated. Any attribute names can be used as long as they are supported
by the target directory.
@param inGroup Specifies the group, which should be searched. NULL means that all
groups should be searched.
@param outResults Points to the results of the search.
@return kSecOk or kSecError
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_customSearch)
( DirConnection inConnection,
DirSearchCriteria inSearchCriteria,
ASText inGroup,
DirResults outResults );
/** Pops up a custom user interface that allows the user to set search criteria and execute the
search.
@param inConnection The connection that is used to perform the search.
@param inGroup Specifies the group, which should be searched. NULL means that all
groups should be searched.
@param outResults Points to the results of the search.
@return kSecOk or kSecError
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_customUISearch)
( DirConnection inConnection,
ASText inGroup,
DirResults outResults );
/** Retrieve all entries in the specified groups. If that would take too long, return
kDirDirectoryTooLargeToList. This may be used in the user interface to immediately display
the contents of a small directory or group, so responsiveness is important.
@param inConnection The connection that is used to list directory entries.
@param inGroup Specifies the group, which should be listed. NULL means that all
groups should be listed.
@param outResults Points to the results of the enumeration.
@return kSecOk, kDirDirectoryTooLargeToList, or kSecError
*/
#define kDirDirectoryTooLargeToList 2
/** TBD */
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_list)
( DirConnection inConnection,
ASText inGroup,
DirResults outResults );
/** Closes the specified directory connection.
*/
typedef ACCBPROTO1 void (ACCBPROTO2 *DirConnection_close)
( DirConnection inConnection );
/** Retrieves information about the directory associated with the connection.
@param inConnection A directory connection object.
@param outDirInfo A Cab file containing the directory information.
@return kSecOk or kSecError
*/
typedef ACCBPROTO1 SecRetCode (ACCBPROTO2 *DirConnection_getDirInfo)
( DirConnection inConnection, DirectoryInfo outDirInfo );
/** Retrieves information about the last error that occurred in the specified
connection.
*/
typedef ACCBPROTO1 SecErrorInfo (ACCBPROTO2 *DirConnection_getLastError)
( DirConnection inConnection );
/** A directory connection object structure.
*/
typedef struct _t_DirConnection
{
/** The size of this data structure. */
ASSize_t size;
/** The data to be passed in. */
void* clientData;
/** */
DirConnection_close close;
/** */
DirConnection_getLastError getLastError;
/** */
DirConnection_getDirInfo getDirInfo;
/** */
DirConnection_getGroups getGroups;
/** */
DirConnection_setStandardOutputOptions setStandardOutputOptions;
/** */
DirConnection_setCustomOutputOptions setCustomOutputOptions;
/* Although all four of these methods are optional, at least one must be present
for a connection to be usable: */
/** */
DirConnection_standardSearch standardSearch;
/** */
DirConnection_customSearch customSearch;
/** */
DirConnection_customUISearch customUISearch;
/** */
DirConnection_list list;
}
DirConnectionRec, *DirConnectionHandler;
#ifdef __cplusplus
}
#endif
#if PRAGMA_STRUCT_ALIGN
#pragma options align=reset
#endif
#endif /* DIR_SERVICES_HFT_H */