contrib/apr/docs/non_apr_programs

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