1How do I use APR'ized programs in connection with programs that don't
2use APR?  These darn incomplete types don't let me fill out the APR types.
3
4The APR developers acknowledge that most programs are not using APR, and
5we don't expect them to migrate to using APR just because APR has been
6released.  So, we have provided a way for non-APR'ized programs to interact
7very cleanly with APR.
8
9There are a set of functions, all documented in apr_portable.h, which allow
10a programmer to either get a native type from an APR type, or to setup an
11APR type from a native type.
12
13For example, if you are writing an add-on to another program that does not use
14APR for file I/O, but you (in your infinite wisdom) want to use APR to make
15sure your section is portable.  Assume the program provides a type foo_t with
16a file descriptor in it (fd).
17
18void function_using_apr(foo_t non_apr_struct, ap_pool_t *p)
19{
20    ap_file_t *apr_file = NULL;
21
22    ap_put_os_file(&apr_file, &non_apr_struct->fd, p);
23
24    ...
25}
26
27There are portable functions for each APR incomplete type.  They are all 
28called ap_put_os_foobar(), and they each take the same basic arguments, a
29pointer to a pointer to the incomplete type (the last pointer in that list 
30should be NULL), a pointer to the native type, and a pool.  Each of these can
31be found in apr_portable.h.
32
33If you have to do the exact opposite (take an APR type and convert it to a 
34native type, there are functions for that too.  For example:
35
36void function_not_using_apr(apr_file_t *apr_file)
37{
38    int unix_file_desc;
39
40    ap_get_os_file(&unix_file_desc, apr_file);
41   
42    ...
43}
44
45For each ap_put_os_foobar, there is a corresponding ap_get_os_file.  These are
46also documented in apr_portable.h.
47
48