Isode ATN Directory Service API Reference Manual Generated by Doxygen 1.4.7

Transcription

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 support@isode.com
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 )
??
5
5 Isode ATN Directory Service API Module Documentation
atnds_cdecl.h
5
3
??
Isode ATN Directory Service API Module Documentation
5.1
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)
Parameters:
ptr [in] Pointer to buffer to free.
Returns:
None
Examples:
atnds_test.c.
5.1
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)
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)
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.
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
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)
• 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)
• DS_Status ATNds_AMHS2AFTN (DS_Session ∗session, const DS_DN
∗registry_dn, const char ∗x400_or_addr, char ∗aftn_buf, DS_DN ∗∗userdn_p)
8 Isode ATN Directory Service API Example Documentation
6
7.1.1
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 *
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;
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 );
}
status = DS_Session_New( call_addr, 0, &ds );
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;
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 );
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, &registry_dn );
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 ) {
}
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 );
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
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 );
}
status = ATNds_AMHS2AFTN( ds, registry_dn, orbuf, aftnbuf, &user_dn );
ATNds_free( ( void * ) orbuf );
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 );
8.1
atnds_test.c
11
278
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
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 );
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 );
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 );
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 );
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 */
}
}
return 0;
8.1
atnds_test.c
402 }
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
ATNds_free

Isode ATN Directory Service API Reference Manual Generated by Doxygen 1.4.7

Transcription

Similar documents

RM People Directory Quick Start - RM

160 eyeliner pencils in one minute. ATN timing belts in... service of beauty

CGTI - CUSTOM GRADE TUBES

Tax and Accounting Sites Directory

Misty's Competitive/Comparative Audit

Gabe Westmaas Rackspace @westmaas

Fun Fun Project One Building Your Very Own Web Server 1

Sze Wong | CEO | Zerion Software, Inc.

2014 SCCA Directory

NJAA-Ad Form 2015 Directory PROOF3