1/* 2 * profile.h 3 */ 4 5#ifndef _KRB5_PROFILE_H 6#define _KRB5_PROFILE_H 7 8#if defined(_WIN32) 9#include <win-mac.h> 10#endif 11 12#if defined(__MACH__) && defined(__APPLE__) 13# include <TargetConditionals.h> 14# if TARGET_RT_MAC_CFM 15# error "Use KfM 4.0 SDK headers for CFM compilation." 16# endif 17#endif 18 19#ifndef KRB5_CALLCONV 20#define KRB5_CALLCONV 21#define KRB5_CALLCONV_C 22#endif 23 24typedef struct _profile_t *profile_t; 25 26/* Used by profile_init_flags(). */ 27#define PROFILE_INIT_ALLOW_MODULE 0x0001 /* Allow module declaration */ 28 29/* 30 * Used by the profile iterator in prof_get.c 31 */ 32#define PROFILE_ITER_LIST_SECTION 0x0001 33#define PROFILE_ITER_SECTIONS_ONLY 0x0002 34#define PROFILE_ITER_RELATIONS_ONLY 0x0004 35 36#ifdef __cplusplus 37extern "C" { 38#endif /* __cplusplus */ 39 40typedef char* profile_filespec_t; /* path as C string */ 41typedef char* profile_filespec_list_t; /* list of : separated paths, C string */ 42typedef const char * const_profile_filespec_t; /* path as C string */ 43typedef const char * const_profile_filespec_list_t; /* list of : separated paths, C string */ 44 45long KRB5_CALLCONV profile_init 46 (const_profile_filespec_t *files, profile_t *ret_profile); 47 48long KRB5_CALLCONV profile_init_flags 49 (const_profile_filespec_t *files, int flags, profile_t *ret_profile); 50 51long KRB5_CALLCONV profile_init_path 52 (const_profile_filespec_list_t filelist, profile_t *ret_profile); 53 54long KRB5_CALLCONV profile_flush 55 (profile_t profile); 56long KRB5_CALLCONV profile_flush_to_file 57 (profile_t profile, const_profile_filespec_t outfile); 58long KRB5_CALLCONV profile_flush_to_buffer 59 (profile_t profile, char **bufp); 60void KRB5_CALLCONV profile_free_buffer 61 (profile_t profile, char *buf); 62 63long KRB5_CALLCONV profile_is_writable 64 (profile_t profile, int *writable); 65long KRB5_CALLCONV profile_is_modified 66 (profile_t profile, int *modified); 67 68void KRB5_CALLCONV profile_abandon 69 (profile_t profile); 70 71void KRB5_CALLCONV profile_release 72 (profile_t profile); 73 74long KRB5_CALLCONV profile_get_values 75 (profile_t profile, const char *const *names, char ***ret_values); 76 77void KRB5_CALLCONV profile_free_list 78 (char **list); 79 80long KRB5_CALLCONV profile_get_string 81 (profile_t profile, const char *name, const char *subname, 82 const char *subsubname, const char *def_val, 83 char **ret_string); 84long KRB5_CALLCONV profile_get_integer 85 (profile_t profile, const char *name, const char *subname, 86 const char *subsubname, int def_val, 87 int *ret_default); 88 89long KRB5_CALLCONV profile_get_boolean 90 (profile_t profile, const char *name, const char *subname, 91 const char *subsubname, int def_val, 92 int *ret_default); 93 94long KRB5_CALLCONV profile_get_relation_names 95 (profile_t profile, const char **names, char ***ret_names); 96 97long KRB5_CALLCONV profile_get_subsection_names 98 (profile_t profile, const char **names, char ***ret_names); 99 100long KRB5_CALLCONV profile_iterator_create 101 (profile_t profile, const char *const *names, 102 int flags, void **ret_iter); 103 104void KRB5_CALLCONV profile_iterator_free 105 (void **iter_p); 106 107long KRB5_CALLCONV profile_iterator 108 (void **iter_p, char **ret_name, char **ret_value); 109 110void KRB5_CALLCONV profile_release_string (char *str); 111 112long KRB5_CALLCONV profile_update_relation 113 (profile_t profile, const char **names, 114 const char *old_value, const char *new_value); 115 116long KRB5_CALLCONV profile_clear_relation 117 (profile_t profile, const char **names); 118 119long KRB5_CALLCONV profile_rename_section 120 (profile_t profile, const char **names, 121 const char *new_name); 122 123long KRB5_CALLCONV profile_add_relation 124 (profile_t profile, const char **names, 125 const char *new_value); 126 127/* 128 * profile_init_vtable allows a caller to create a profile-compatible object 129 * with a different back end. 130 */ 131 132/* 133 * Mandatory: Look up all of the relations for names, placing the resulting 134 * values in *ret_values. If no relations exist, return PROF_NO_RELATION, or 135 * PROF_NO_SECTION to indicate that one of the intermediate names does not 136 * exist as a section. The list will be freed with free_values. 137 */ 138typedef long 139(*profile_get_values_fn)(void *cbdata, const char *const *names, 140 char ***ret_values); 141 142/* Mandatory: Free a list of strings returned by get_values. */ 143typedef void 144(*profile_free_values_fn)(void *cbdata, char **values); 145 146/* Optional: Release any data associated with the profile. */ 147typedef void 148(*profile_cleanup_fn)(void *cbdata); 149 150/* 151 * Optional (mandatory if cleanup is defined): Generate a new cbdata pointer 152 * for a copy of the profile. If not implemented, the new profile will receive 153 * the same cbdata pointer as the old one. 154 */ 155typedef long 156(*profile_copy_fn)(void *cbdata, void **ret_cbdata); 157 158/* 159 * Optional: Create an iterator handle. 160 * 161 * If flags contains PROFILE_ITER_LIST_SECTION, iterate over all of the 162 * relations and sections within names. Otherwise, iterate over the relation 163 * values for names, or produce a single section result if names is a section. 164 * 165 * If flags contains PROFILE_ITER_SECTIONS_ONLY, produce only sections. 166 * 167 * If flags contains PROFILE_ITER_RELATIONS_ONLY, produce only relations. 168 */ 169typedef long 170(*profile_iterator_create_fn)(void *cbdata, const char *const *names, 171 int flags, void **ret_iter); 172 173/* 174 * Optional (mandatory if iterator_create is defined): Produce the next 175 * relation or section in an iteration. If producing a section result, set 176 * *ret_value to NULL. The returned strings will be freed with free_string. 177 */ 178typedef long 179(*profile_iterator_fn)(void *cbdata, void *iter, char **ret_name, 180 char **ret_value); 181 182/* 183 * Optional (mandatory if iterator_create is defined): Free the memory for an 184 * iterator. 185 */ 186typedef void 187(*profile_iterator_free_fn)(void *cbdata, void *iter); 188 189/* Optional (mandatory if iterator is defined): Free a string value. */ 190typedef void 191(*profile_free_string_fn)(void *cbdata, char *string); 192 193/* 194 * Optional: Determine if a profile is writable. If not implemented, the 195 * profile is never writable. 196 */ 197typedef long 198(*profile_writable_fn)(void *cbdata, int *writable); 199 200/* 201 * Optional: Determine if a profile is modified in memory relative to the 202 * persistent store. If not implemented, the profile is assumed to never be 203 * modified. 204 */ 205typedef long 206(*profile_modified_fn)(void *cbdata, int *modified); 207 208/* 209 * Optional: Change the value of a relation, or remove it if new_value is NULL. 210 * If old_value is set and the relation does not have that value, return 211 * PROF_NO_RELATION. 212 */ 213typedef long 214(*profile_update_relation_fn)(void *cbdata, const char **names, 215 const char *old_value, const char *new_value); 216 217/* 218 * Optional: Rename a section to new_name, or remove the section if new_name is 219 * NULL. 220 */ 221typedef long 222(*profile_rename_section_fn)(void *cbdata, const char **names, 223 const char *new_name); 224 225/* 226 * Optional: Add a new relation, or a new section if new_value is NULL. Add 227 * any intermediate sections as necessary. 228 */ 229typedef long 230(*profile_add_relation_fn)(void *cbdata, const char **names, 231 const char *new_value); 232 233/* 234 * Optional: Flush any pending memory updates to the persistent store. If 235 * implemented, this function will be called by profile_release as well as 236 * profile_flush, so make sure it's not inefficient to flush an unmodified 237 * profile. 238 */ 239typedef long 240(*profile_flush_fn)(void *cbdata); 241 242struct profile_vtable { 243 int minor_ver; /* Set to structure minor version (currently 1) 244 * if calling profile_init_vtable. */ 245 246 /* Methods needed for a basic read-only non-iterable profile (cleanup is 247 * optional). */ 248 profile_get_values_fn get_values; 249 profile_free_values_fn free_values; 250 profile_cleanup_fn cleanup; 251 profile_copy_fn copy; 252 253 /* Methods for iterable profiles. */ 254 profile_iterator_create_fn iterator_create; 255 profile_iterator_fn iterator; 256 profile_iterator_free_fn iterator_free; 257 profile_free_string_fn free_string; 258 259 /* Methods for writable profiles. */ 260 profile_writable_fn writable; 261 profile_modified_fn modified; 262 profile_update_relation_fn update_relation; 263 profile_rename_section_fn rename_section; 264 profile_add_relation_fn add_relation; 265 profile_flush_fn flush; 266 267 /* End of minor version 1. */ 268}; 269 270/* 271 * Create a profile object whose operations will be performed using the 272 * function pointers in vtable. cbdata will be supplied to each vtable 273 * function as the first argument. 274 */ 275long KRB5_CALLCONV profile_init_vtable 276 (struct profile_vtable *vtable, void *cbdata, profile_t *ret_profile); 277 278/* 279 * Dynamically loadable profile modules should define a function named 280 * "profile_module_init" matching the following signature. The function should 281 * initialize the methods of the provided vtable structure, stopping at the 282 * field corresponding to vtable->minor_ver. Do not change the value of 283 * vtable->minor_ver. Unimplemented methods can be left uninitialized. The 284 * function should supply a callback data pointer in *cb_ret; this pointer can 285 * be cleaned up via the vtable cleanup method. 286 */ 287typedef long 288(*profile_module_init_fn)(const char *residual, struct profile_vtable *vtable, 289 void **cb_ret); 290 291#ifdef __cplusplus 292} 293#endif /* __cplusplus */ 294 295#endif /* _KRB5_PROFILE_H */ 296