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