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