usr/src/lib/libidmap/common/directory.h

   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 */