Isode ATN Directory Service API Reference Manual Generated by Doxygen 1.4.7
Isode ATN Directory Service API Reference Manual Generated by Doxygen 1.4.7 Thu Jun 5 03:21:25 2014 CONTENTS 1 Contents 1 Isode ATN Directory Service Client API 1 2 Isode ATN Directory Service API Module Index 2 3 Isode ATN Directory Service API Data Structure Index 2 4 Isode ATN Directory Service API File Index 2 5 Isode ATN Directory Service API Module Documentation 3 6 Isode ATN Directory Service API Data Structure Documentation 5 7 Isode ATN Directory Service API File Documentation 5 8 Isode ATN Directory Service API Example Documentation 6 1 Isode ATN Directory Service Client API ATN Directory Service Client Library API Specification 1.1 Version 1.0 1.2 (c) 2005-2013, Isode Limited, London, England. 1.3 Introduction This document is a specification of the Isode ATN Directory Service Library API. Note that this API requires and operates in conjunction with the Isode Simple Directory Service Library API, which is documented separately. The ATNDS (Aeronautical Telecommunications Network Directory Service) API contains utility functions to: • Convert AFTN addresses to the corresponding AMHS address. See ATNds_AFTN2AMHS(). • Convert AMHS addresses to the corresponding AFTN address. See ATNds_AMHS2AFTN(). • Get the AMHS terminal directory entry name associated with AFTN or AMHS addresses. The ATN DS API works in conjunction with the DSAPI and simple directory operations (bind, read an entry, etc.) are performed using this. Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 1.4 Using ATNDS 1.4 2 Using ATNDS The API works in conjunction with DSAPI. As such, clients will need to use DSAPI functions to bind and unbind from the directory and perform any necessary additional queries (for example reading the entry of an AMHS terminal in order to determine its capabilities). The session handle returned from the bind functions is necessary for calls to ATNDS API functions. 1.5 Example • ATN address conversion: atnds_test.c. This example converts between AFTN (both XF and CAAS style) and AMHS addresses, and prints the results out to the console. The example shows how DSAPI is used to establish a connection to the directory. Please send any comments on the API to [email protected] 2 Isode ATN Directory Service API Module Index 2.1 Isode ATN Directory Service API Modules Here is a list of all modules: ATN Address Conversion Functions 3 3 Isode ATN Directory Service API Data Structure Index 3.1 Isode ATN Directory Service API Data Structures Here are the data structures with brief descriptions: ATN_NC 4 5 Isode ATN Directory Service API File Index 4.1 Isode ATN Directory Service API File List Here is a list of all documented files with brief descriptions: atn-syntax.h atnds.h (ATN directory service client functions ) Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen ?? 5 5 Isode ATN Directory Service API Module Documentation atnds_cdecl.h 5 3 ?? Isode ATN Directory Service API Module Documentation 5.1 ATN Address Conversion Functions Functions • void ATNds_free (void ∗ptr) Free a buffer which has been returned by ATNds_AFTN2AMHS or ATNds_AMHS2AFTN. • DS_Status ATNds_AFTN2AMHS (DS_Session ∗session, const DS_DN ∗registry_dn, const char ∗aftn_addr, char ∗∗orbuf_p, size_t ∗orbuf_len_p, DS_DN ∗∗userdn_p) Convert an AFTN address to the AMHS O/R address. If the user has an associated directory entry the distinguished name of that is returned as well. • DS_Status ATNds_AMHS2AFTN (DS_Session ∗session, const DS_DN ∗registry_dn, const char ∗x400_or_addr, char ∗aftn_buf, DS_DN ∗∗userdn_p) Return the AFTN address associated with the given AMHS O/R address. If the user has an associated directory entry the distinguished name of this is returned as well. 5.1.1 Detailed Description Functions of the ATN directory service client API. 5.1.2 Function Documentation 5.1.2.1 void ATNds_free (void ∗ ptr) Free a buffer which has been returned by ATNds_AFTN2AMHS or ATNds_AMHS2AFTN. Parameters: ptr [in] Pointer to buffer to free. Returns: None Examples: atnds_test.c. Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 5.1 ATN Address Conversion Functions 4 5.1.2.2 DS_Status ATNds_AFTN2AMHS (DS_Session ∗ session, const DS_DN ∗ registry_dn, const char ∗ aftn_addr, char ∗∗ orbuf_p, size_t ∗ orbuf_len_p, DS_DN ∗∗ userdn_p) Convert an AFTN address to the AMHS O/R address. If the user has an associated directory entry the distinguished name of that is returned as well. Parameters: session [in] An open directory session. registry_dn [in] DN of ICAO or local registry. aftn_addr [in] AFTN address to convert. orbuf_p [out] Returned O/R address string, or NULL if the address could not be found. orbuf_len_p [out] Length of returned buffer, or 0 if the address could not be found. userdn_p [out] Returned DN (of user entry). NULL if none found. Returns: DS_E_NOERROR on success or non-zero error code. Note that DS_E_NOERROR can still be returned when the address could not be found. Examples: atnds_test.c. 5.1.2.3 DS_Status ATNds_AMHS2AFTN (DS_Session ∗ session, const DS_DN ∗ registry_dn, const char ∗ x400_or_addr, char ∗ aftn_buf, DS_DN ∗∗ userdn_p) Return the AFTN address associated with the given AMHS O/R address. If the user has an associated directory entry the distinguished name of this is returned as well. Parameters: session [in] An open directory session. registry_dn [in] DN of ICAO or local registry. x400_or_addr [in] X400 O/R address to convert. aftn_buf [out] A buffer of length 9 which will hold the returned AFTN address. This buffer is allocated and owned by the caller. userdn_p [out] Returned DN (of user entry). Returns: DS_E_NOERROR on success or non-zero error code. Examples: atnds_test.c. Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 6 Isode ATN Directory Service API Data Structure Documentation 6 5 Isode ATN Directory Service API Data Structure Documentation 6.1 ATN_NC Struct Reference Data Fields • int offset • union { char ∗ str dncomp ∗ dn } un 6.1.1 Detailed Description Definition at line 30 of file atn-syntax.h. The documentation for this struct was generated from the following file: • atn-syntax.h 7 7.1 Isode ATN Directory Service API File Documentation atnds.h File Reference ATN directory service client functions. #include <isode/ds/dsapi/dsapi.h> #include <isode/ds/atnds/atnds_cdecl.h> Functions • void ATNds_free (void ∗ptr) Free a buffer which has been returned by ATNds_AFTN2AMHS or ATNds_AMHS2AFTN. • DS_Status ATNds_AFTN2AMHS (DS_Session ∗session, const DS_DN ∗registry_dn, const char ∗aftn_addr, char ∗∗orbuf_p, size_t ∗orbuf_len_p, DS_DN ∗∗userdn_p) Convert an AFTN address to the AMHS O/R address. If the user has an associated directory entry the distinguished name of that is returned as well. • DS_Status ATNds_AMHS2AFTN (DS_Session ∗session, const DS_DN ∗registry_dn, const char ∗x400_or_addr, char ∗aftn_buf, DS_DN ∗∗userdn_p) Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8 Isode ATN Directory Service API Example Documentation 6 Return the AFTN address associated with the given AMHS O/R address. If the user has an associated directory entry the distinguished name of this is returned as well. 7.1.1 Detailed Description ATN directory service client functions. This is the set of functions used to perform ATN address conversion, addressbook lookup and management. Definition in file atnds.h. 8 Isode ATN Directory Service API Example Documentation 8.1 atnds_test.c This extended example shows how to convert AFTN address to the corresponding AMHS form, and vice versa. The example also makes use of DSAPI to connect to the directory and manipulate directory data. To compile this example on Unix machines: cc -c -I/opt/isode/include/isode/ds/atnds/ -I/opt/isode/include -I/opt/isode/include/h To link this example on Unix machines: cc -o atnds_test atnds_test.o -L/opt/isode/lib \ -latnds -ldua -lisode -libase -lmdldap -lmdlber -lssl -lcrypto 1 /* Copyright (c) 2004-2010, Isode Limited, London, England. 2 * All rights reserved. 3 * 4 * Acquisition and use of this software and related materials for any 5 * purpose requires a written licence agreement from Isode Limited, 6 * or a written licence from an organisation licenced by Isode Limited 7 * to grant such a licence. 8 * 9 */ 10 11 /* 12 * atnds_test.c 13 * 14 * Test functions of ATNds C library. 15 * 16 */ 17 18 /* 19 * Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 atnds_test.c 20 21 22 23 24 25 26 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 * @VERSION@ */ 7 #include <stdio.h> #include <string.h> #include <isode/ds/atnds/atnds.h> DS_Session *ds; static int read_atn_user (const char *prog, DS_DN *user_dn); static const char underline[] = "----------------------------------------------------------------"; static void usage(const char *prog) { fprintf( stderr, "Usage: %s " "[-call presentation-address] " "[-dn registry-dn] " "[-read] " "[-nodn] " "[-inverse] " "[-verbose] " "aftn/caas/xf-address\n", prog ); } int main( int argc, char *argv[] ) { const char *call_addr = "Internet=localhost+19999"; const char *registry_dn_str = "o=Isode-MD-Register"; int read_entry = 0; int inverse = 0; int verbose = 0; int show_dn = 1; int arg = 1; DS_DN *registry_dn; DS_DN *user_dn; char *orbuf; size_t orbuf_len; DS_Session *ds; DS_Indication *di = NULL; DS_Status status; DS_ErrorType t; DS_ErrorValue v; char *dnbuf; size_t dnbuf_len; char aftnbuf[9]; /* Avoid getopt() as it doesn’t exist everywhere */ while ( arg < argc && argv[arg][0] == ’-’ ) { if ( strncmp( argv[arg], "-call", strlen( argv[arg] ) ) == 0 ) { if ( arg + 1 <= argc ) { call_addr = argv[arg + 1]; arg += 2; continue; } } if ( strncmp( argv[arg], "-dn", strlen( argv[arg] ) ) == 0 ) { if ( arg + 1 <= argc ) { registry_dn_str = argv[arg + 1]; arg += 2; continue; Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 atnds_test.c } } if ( strncmp( argv[arg], "-nodn", strlen( argv[arg] ) ) show_dn = 0; arg++; continue; } if ( strncmp( argv[arg], "-read", strlen( argv[arg] ) ) read_entry = 1; arg++; continue; } if ( strncmp( argv[arg], "-inverse", strlen( argv[arg] inverse = 1; arg++; continue; } if ( strncmp( argv[arg], "-verbose", strlen( argv[arg] verbose = 1; arg++; continue; } usage( argv[0] ); return 1; 8 == 0 ) { == 0 ) { ) ) == 0 ) { ) ) == 0 ) { } /* argv[arg] should be the address to convert */ if ( arg != argc - 1 ) { usage( argv[0] ); return 1; } /* Initialize the DUA library. */ if ( verbose ) { printf( "\nTEST: initializing DUA library %s.\n", call_addr ); printf( "%s\n", underline ); } status = DS_Initialize(); if ( status != DS_E_NOERROR ) { fprintf( stderr, "%s: couldn’t initialize DUA library\n", argv[0] ); return status; } /* Attempt to bind." */ if ( verbose ) { printf( "\nTEST: bind (to %s)\n", call_addr ); printf( "%s\n", underline ); } status = DS_Session_New( call_addr, 0, &ds ); if ( status != DS_E_NOERROR ) { fprintf( stderr, "%s: failed to create session\n", argv[0] ); return 1; } status = DS_BindAnonymousSync( ds, NULL, &di ); if ( ! ( DS_Indication_GetErrorCodes( di, &t, &v ) == DS_E_NOERROR && t == DS_E_SUCCESS ) ) status = DS_E_DSOPFAILED; Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 atnds_test.c 9 DS_Indication_Delete( di ); if ( status != DS_E_NOERROR ) { DS_UnbindSync( &ds ); fprintf( stderr, "%s: couldn’t bind to directory\n", argv[0] ); return 1; } if ( verbose ) { printf( "SUCCESS: bound to directory\n" ); } /* Convert string registry DN to DSAPI DN structure. */ status = DS_String2DN( registry_dn_str, ®istry_dn ); if ( status != DS_E_NOERROR ) { fprintf ( stderr, "%s: error converting DN (%s)\n", argv[0], registry_dn_str ); return DS_E_BADDN; } if ( verbose ) { printf( "\nTEST: convert to X.400 (%s)\n", argv[arg] ); } status = ATNds_AFTN2AMHS( ds, registry_dn, argv[arg], &orbuf, &orbuf_len, &user_dn ); if ( verbose ) { printf( "%s\n", underline ); } if ( status != DS_E_NOERROR ) { switch ( status ) { case DS_E_NOTFOUND: fprintf( stderr, "%s: conversion data not found " "in the ATN directory\n", argv[0] ); return status; default: fprintf ( stderr, "%s: conversion failed " "(%d - no error message available)\n", argv[0], status ); return status; } } if ( verbose ) { printf( "SUCCESS: conversion succeeded.\n" ); printf( "DETAIL: O/R address is %s\n\n", orbuf ); } else { printf( "X.400 = %s\n", orbuf ); } if ( user_dn != NULL ) { status = DS_DN2String( user_dn, &dnbuf, &dnbuf_len ); Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 atnds_test.c 10 if ( status != DS_E_NOERROR ) { fprintf( stderr, "%s: failed to parse aMHSUser entry DN\n", argv[0] ); } else { if ( verbose ) { printf( "DETAIL: aMHSUser entry DN is %s.\n", dnbuf ); } else if ( show_dn ) { printf( "User DN = %s\n", dnbuf ); } ATNds_free( dnbuf ); } DS_DN_Delete( user_dn ); } else { if ( verbose ) { printf( "DETAIL: no aMHSUser entry DN could be computed.\n"); } } /* Return now unless we want to do the inverse mapping. */ if ( inverse == 0 ) { return 0; } /* Perform inverse conversion. */ if ( verbose ) { printf( "\nTEST: performing inverse conversion\n(from %s)\n", orbuf ); printf( "%s\n", underline ); } status = ATNds_AMHS2AFTN( ds, registry_dn, orbuf, aftnbuf, &user_dn ); ATNds_free( ( void * ) orbuf ); if ( status != DS_E_NOERROR ) { switch ( status ) { case DS_E_NOTFOUND: fprintf( stderr, "%s: conversion data not available\n", argv[0] ); return status; default: fprintf ( stderr, "%s: conversion failed " "(%d - no error message available)\n", argv[0], status ); return status; } } if ( verbose ) { printf( "SUCCESS: conversion succeeded.\n" ); printf( "DETAIL: AFTN address is %s\n", aftnbuf ); } else { printf( "AFTN (inverse) = %s\n", aftnbuf ); } if ( user_dn != NULL ) { status = DS_DN2String( user_dn, &dnbuf, &dnbuf_len ); Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 atnds_test.c 11 278 if ( status != DS_E_NOERROR ) { 279 fprintf( stderr, "%s: failed to display aMHSUser entry DN\n", 280 argv[0] ); 281 } else { 282 if ( verbose ) { 283 printf( "DETAIL: aMHSUser entry DN is %s.\n", dnbuf ); 284 } else if ( show_dn ) { 285 printf( "User DN (inverse) = %s\n", dnbuf ); 286 } 287 ATNds_free( dnbuf ); 288 } 289 290 if ( read_entry ) 291 read_atn_user( argv[0], user_dn ); 292 293 DS_DN_Delete( user_dn ); 294 295 } else { 296 if ( verbose ) { 297 printf( "DETAIL: no aMHSUser entry DN could be computed.\n"); 298 } 299 } 300 301 /* Clean up. */ 302 DS_DN_Delete( registry_dn ); 303 304 /* Unbind from the DSA */ 305 DS_UnbindSync( &ds ); 306 307 /* All tests done. */ 308 return 0; 309 310 } 311 312 313 static int 314 read_atn_user ( const char *prog, DS_DN *user_dn ) { 315 316 DS_Indication *di = NULL; 317 const DS_EntryList *el; 318 const DS_Entry *e; 319 const DS_AttrList *al; 320 const DS_Attr *a; 321 DS_ErrorType t; 322 DS_ErrorValue v; 323 DS_ErrorType type_p; 324 int status; 325 326 327 status = DS_ReadSync( ds, user_dn, NULL, NULL, &di ); 328 if ( status != DS_E_NOERROR ) { 329 if ( di != NULL ) { 330 DS_Indication_GetStatus ( di, &type_p ) ; 331 DS_Indication_Delete ( di ); 332 if ( type_p == DS_E_NAME ) { 333 fprintf( stderr, "%s: No DSA entry for this ATN User entry\n", 334 prog ); 335 return 0; 336 } 337 } 338 fprintf( stderr, "%s: Failed to read ATN User entry (status=%d)\n", 339 prog, status ); Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 atnds_test.c 12 return 1; } if ( ! ( DS_Indication_GetErrorCodes( di, &t, &v ) == DS_E_NOERROR && t == DS_E_SUCCESS ) ) return 1; } status = DS_Indication_GetEntryList( di, &el ); if ( status != DS_E_NOERROR ) { DS_Indication_Delete ( di ); fprintf( stderr, "%s: Failed to read ATN User entry Indication\n", prog ); return 2; } e = DS_EntryList_GetFirst( el ); status = DS_Entry_GetAttrList( e, &al ); if ( status != DS_E_NOERROR ) { DS_Indication_Delete ( di ); fprintf( stderr, "%s: Failed to read attribute list for " "ATN User entry\n", prog ); return 3; } for ( a = DS_AttrList_GetFirst( al ); a != NULL; a = DS_AttrList_GetNext( a ) ) { const char *name; const DS_AttrValList *vl; const DS_AttrVal *v; DS_Attr_GetTypeName( a, &name ); /* Don’t free name */ status = DS_Attr_GetValueList( a, &vl ); if ( status != DS_E_NOERROR ) { DS_Indication_Delete ( di ); fprintf( stderr, "%s: Failed to read attribute values for " "ATN User entry\n", prog ); return 4; } for ( v = DS_AttrValList_GetFirst( vl ); v != NULL; v = DS_AttrValList_GetNext( v ) ) { const char *val_str; size_t val_len; status = DS_AttrVal_GetStringPointer( v, &val_str, &val_len ); if ( status == DS_E_NOERROR ) printf( "%s: %s\n", name, val_str ); else printf( "%s: (No string value)\n", name ); /* Don’t free val_str */ } } DS_Indication_Delete ( di ); return 0; Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 8.1 atnds_test.c 402 } Generated on Thu Jun 5 03:21:25 2014 for Isode ATN Directory Service API by Doxygen 13 Index ATN Address Conversion Functions, 2 ATN_NC, 4 atndir_conversion ATNds_AFTN2AMHS, 3 ATNds_AMHS2AFTN, 4 ATNds_free, 3 atnds.h, 5 ATNds_AFTN2AMHS atndir_conversion, 3 ATNds_AMHS2AFTN atndir_conversion, 4 ATNds_free atndir_conversion, 3
© Copyright 2024