diff options
Diffstat (limited to 'Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/DirectoryHFT.h')
| -rw-r--r-- | Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/DirectoryHFT.h | 393 |
1 files changed, 393 insertions, 0 deletions
diff --git a/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/DirectoryHFT.h b/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/DirectoryHFT.h new file mode 100644 index 0000000..273b797 --- /dev/null +++ b/Adobe_SigHandler/Adobe.PDF-AS-SigHandler/sources/import/API/DirectoryHFT.h @@ -0,0 +1,393 @@ +/*************************************************************************
+ * DirectoryHFT.h
+ *
+ * Copyright (c) 2000-2006 Adobe Systems Inc. All Rights Reserved.
+ *
+ * NOTICE: All information contained herein is, and remains the
+ * property of Adobe Systems Incorporated and its suppliers, if any.
+ * The intellectual and technical concepts contained herein are
+ * proprietary to Adobe Systems Incorporated and its suppliers and may
+ * be covered by U.S. and Foreign Patents, patents in process, and are
+ * protected by trade secret or copyright law. Dissemination of this
+ * information or reproduction of this material is strictly forbidden
+ * unless prior written permission is obtained from Adobe Systems Inc.
+ *
+ * Description: Interface to Acrobat Directory Services
+ *
+ * 06-20-2002 sheretov -- Created
+ ************************************************************************/
+
+#ifndef DIR_SERVICES_HFT_H
+#define DIR_SERVICES_HFT_H
+
+#include "CoreExpT.h"
+
+#if PRAGMA_STRUCT_ALIGN
+ #if __MWERKS__
+ #pragma options align=power_gcc
+ #elif __GNUC__
+ #pragma options align=power
+ #else
+ #error
+ #endif
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/************************************************************************************
+ * Error handling
+ ***********************************************************************************/
+
+/** @name Error handling */
+ /*@{*/
+/** */
+typedef ASInt32 SecRetCode;
+/** */
+#define kSecTrue 1
+/** */
+#define kSecFalse 0
+/** */
+#define kSecOk 1
+/** */
+#define kSecError -1
+/*@}*/
+
+/** If a function returns <code>-1</code> or less, you can call a <code>GetLastError</code> appropriate to
+ the context and retrieve information about the last error. That call may
+ return <code>NULL</code> 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 <code>NULL</code> 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 <code>DirStdEntry_</code> 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 <code>"Adobe Employees"</code>.
+
+ <p>TEXT, REQUIRED.</p> */
+#define PROP_DirectoryInfo_Name "dirStdEntryName"
+
+/* The ID. It is a unique atom that identifies the directory.
+ An example of this would be <code>Adobe.PPKMS.LDAP.dir0</code>.
+ <p> ATOM, REQUIRED.</p> */
+#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 be <code>Adobe.PPKMS.ADSI</code>.
+
+ <p>ATOM, OPTIONAL.</p> */
+#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 be <code>LDAP, ADSI</code>.
+
+ <p>ATOM, OPTIONAL.</p> */
+#define PROP_DirectoryInfo_DirType "dirStdEntryDirType"
+
+/* An integer that represent the version of the directory.
+
+ <p>Integer, OPTIONAL.</p> */
+#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:
+ <p><code>{ ("0", "friends"), ("1", "family"), ... } </code></p>
+*/
+typedef ASCab DirGroupList;
+/** Retrieves the list of groups that this connection supports.
+
+ @return <code>kSecOk</code> is successful, <code>kSecError</code> 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.
+
+ <p>The collection is represented in an ASCab as:</p>
+ <p><code>{ ("0", "nameOfAttribute1"), ("1", "nameOfAttribute2"), ... } </code></p>
+*/
+typedef ASCab DirAttributes;
+
+/** Special case: The <code>ATTR_Certificates</code> attribute is intended to encompass all
+ certificate attributes a directory might have. If <code>ATTR_Certificates</code> 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 <i>standard</i> attribute names defined as <code>ATTR_</code>
+ 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, <code>ATTR_LastName</code> may be interpreted as <code>"sn"</code>.
+ @param outUnsupportedAttrs Used to pass back the the names of attributes (from
+ <code>inRequestedAttrs</code>) that are not supported by the connection.
+ @return <code>kOK</code> or <code>kSecError</code>
+*/
+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
+ <code>inRequestedAttrs</code>) that are not supported by the connection.
+ @return <code>kSecOk</code> or <code>kSecError</code>
+*/
+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 <code>{ ("firstName", "John"), ("lastName", "S*") }</code> searches for people with
+ the first name "John" whose last name starts with letter 'S'.
+
+ @note Special Case: For a <i>standard</i> search, the value of the <code>ATTR_Certificates</code> 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
+ <p><code>{ ("0", { ("fullName", "John Doe"), ("email", "johndoe@yahoo.com") } ),</code></p>
+ <p><code>("1", { ("fullName", "Jane Doe"), ("email", "janedoe@hotmail.com") } ) }</code></p>
+
+
+ @note Special Case: If standard output options are used and <code>ATTR_Certificates</code> is
+ included, the <code>ATTR_Certificates</code> value in the <i>row</i> ASCab objects will be another ASCab,
+ which stores all certificates associated with that directory entry.
+
+ @example <code>
+ { ("0", { ("fullName", John Doe"), ("certificates", { ("0", encryptionCertBinaryValue), ("1", signingCertBinaryValue) } ) } ) }
+ </code>
+*/
+typedef ASCab DirResults;
+
+/** TBD
+ @param inConnection The connection that is used to perform the search.
+ @param inSearchCriteria Search criteria to be used. The only <i>standard</i> attribute
+ names defined as <code>ATTR_</code> 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, <code>ATTR_LastName</code> may be
+ interpreted as <code>"sn"</code>.
+ @param inGroup Specifies the group, which should be searched. <code>NULL</code> means that all
+ groups should be searched.
+ @param outResults Points to the results of the search.
+ @return <code>kSecOk</code> or <code>kSecError</code>
+*/
+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. <code>NULL</code> means that all
+ groups should be searched.
+ @param outResults Points to the results of the search.
+ @return <code>kSecOk</code> or <code>kSecError</code>
+*/
+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. <code>NULL</code> means that all
+ groups should be searched.
+ @param outResults Points to the results of the search.
+ @return <code>kSecOk</code> or <code>kSecError</code>
+*/
+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
+ <code>kDirDirectoryTooLargeToList</code>. 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. <code>NULL</code> means that all
+ groups should be listed.
+ @param outResults Points to the results of the enumeration.
+ @return <code>kSecOk</code>, <code>kDirDirectoryTooLargeToList</code>, or <code>kSecError</code>
+*/
+
+#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 <code>kSecOk</code> or <code>kSecError</code>
+*/
+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 */
|