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