xref: /titanic_41/usr/src/lib/libidmap/common/directory.h (revision 1fcced4c370617db71610fecffd5451a5894ca5e)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef _DIRECTORY_H
28 #define	_DIRECTORY_H
29 
30 /*
31  * A suite of functions for retrieving information about objects
32  * in a directory service.
33  *
34  * Currently it is limited to retrieving SIDs from names, and vice
35  * versa.
36  */
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 #include <sys/types.h>
43 
44 /*
45  * This bitmap is a distillation of the objectClass attribute,
46  * reporting those classes that Solaris finds "interesting".
47  *
48  * All undefined bits are reserved and must be ignored.
49  */
50 #define	DIRECTORY_CLASS_USER	0x0000000000000001
51 #define	DIRECTORY_CLASS_GROUP	0x0000000000000002
52 
53 /*
54  * Opaque pointer to a directory search context.
55  */
56 typedef struct directory *directory_t;
57 
58 /*
59  * Opaque pointer to a structure that describes an error.
60  * Note that NULL means no error.
61  */
62 typedef struct directory_error *directory_error_t;
63 
64 /*
65  * Initialize a directory query session, returning in *d a directory_t
66  * that should be used for query transactions.
67  */
68 directory_error_t directory_open(directory_t *d);
69 
70 /*
71  * Tear down a directory query session.
72  * There is an argument that this should return a directory_error_t, but
73  * then what state would the directory_t be in, and what should you do
74  * if you were doing the directory_close as a result of encountering an error?
75  *
76  * Does nothing if d==NULL.
77  */
78 void directory_close(directory_t d);
79 
80 /*
81  * All directory_t functions return NULL on success or a pointer to a
82  * directory_error_t structure on failure.  The caller must call
83  * directory_error_free() on any non-NULL directory_error_t structures returned.
84  *
85  * Strings returned from the directory_error functions are are
86  * invalidated when the directory_error_t itself is freed.
87  */
88 
89 directory_error_t directory_error(const char *code, const char *fmt, ...);
90 
91 /*
92  * Determines whether this directory_error_t is an instance of the
93  * particular error, or a subclass of that error.
94  */
95 boolean_t directory_error_is_instance_of(directory_error_t de,
96     char *error_string);
97 
98 /*
99  * Returns a printable version of this directory_error_t, suitable for
100  * human consumption.
101  *
102  * The string returned is valid as long as the directory_error_t itself is
103  * valid, and is freed when the directory_error_t is freed.
104  */
105 const char *directory_error_printable(directory_error_t de);
106 
107 /*
108  * Returns the error code for the particular error, as a string.
109  * Note that this function should not normally be used to answer
110  * the question "did error X happen", since the value returned
111  * could be a subclass of X.  directory_error_is_instance_of is intended
112  * to answer that question.  This function is more appropriate for
113  * logging, where one would want to log the error code and the list
114  * of parameters so as to allow structured analysis of the error
115  * after the fact.
116  *
117  * The string returned is valid as long as the directory_error_t itself is
118  * valid, and is freed when the directory_error_t is freed.
119  */
120 const char *directory_error_code(directory_error_t de);
121 
122 /*
123  * Returns one of the parameters of the directory_error_t, or NULL if
124  * the parameter does not exist.
125  *
126  * Note that by definition error subclasses have initial parameters
127  * the same as their superclasses.
128  *
129  * The string returned is valid as long as the directory_error_t itself is
130  * valid, and is freed when the directory_error_t is freed.
131  */
132 const char *directory_error_param(directory_error_t de, int param);
133 
134 /*
135  * Frees the memory (if any) allocated for the directory_error_t.
136  * This frees all strings that might have been derived from this
137  * directory_error_t through directory_error_code, directory_error_printable,
138  * et cetera.
139  *
140  * Does nothing if de==NULL.
141  */
142 void directory_error_free(directory_error_t de);
143 
144 /*
145  * Utility functions to look up a SID given a name, and vice versa.
146  * Caller must free() the result (sid or name, respectively).
147  */
148 directory_error_t directory_sid_from_name(directory_t d, char *name, char **sid,
149     uint64_t *classes);
150 directory_error_t directory_sid_from_user_name(directory_t d, char *name,
151     char **sid);
152 directory_error_t directory_sid_from_group_name(directory_t d, char *name,
153     char **sid);
154 directory_error_t directory_name_from_sid(directory_t d, char *sid, char **name,
155     uint64_t *classes);
156 directory_error_t directory_canon_from_name(directory_t d, char *name,
157     char **canon, uint64_t *classes);
158 directory_error_t directory_canon_from_user_name(directory_t d, char *name,
159     char **canon);
160 directory_error_t directory_canon_from_group_name(directory_t d, char *name,
161     char **canon);
162 
163 #ifdef __cplusplus
164 }
165 #endif
166 
167 #endif /* _DIRECTORY_H */
168