xsbuilder.osc2002.pod

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

    array_header	|
    dav_buffer	|
    dav_dyn_context	|
    dav_dyn_hooks	|
    dav_dyn_module	|
    dav_dyn_provider	|
    dav_error	|
    dav_get_props_result	|
    dav_hooks_liveprop	|
    dav_hooks_locks	|
    dav_hooks_repository	|
    dav_if_header	|
    dav_if_state_type	|
    ...

=head2 Add Perl classes

    struct array_header         | Apache::Array
    struct dav_buffer           |
    struct dav_datum            | Apache::DAV::Datum
    struct dav_dyn_context      | Apache::DAV::DynContext
    struct dav_dyn_hooks        | Apache::DAV::DynHooks
    struct dav_dyn_module       | Apache::DAV::DynModule
    struct dav_dyn_provider     | Apache::DAV::DynProvider
    struct dav_error            | Apache::DAV::Error
    struct dav_get_props_result | Apache::DAV::PropsResult
    struct dav_hooks_db         | Apache::DAV::HooksDb
    struct dav_hooks_liveprop   | Apache::DAV::HooksLiveprop
    struct dav_hooks_locks      | Apache::DAV::HooksLocks
    struct dav_hooks_repository | Apache::DAV::HooksRepository
    struct dav_hooks_vsn        | 
    struct dav_if_header        | Apache::DAV::IfHeader
    struct dav_if_state_list    | Apache::DAV::StateList
    ...
    struct pool                 | Apache::Pool
    struct request_rec          | Apache::
    struct server_rec           | Apache::Server
    ...

Defines the mapping from C datatypes to Perl datatypes and classes
and tells XSBuilder which datatype are (like) structures

=head1 function map

Function map defines the mapping from C functions arguments to Perl arguments

=over 

=item Tell XSBuilder where to place functions and which prefix to strip

    MODULE=Apache::DAV   PACKAGE=guess	PREFIX=dav_

=item Simple entries in the function map will be mapped 1:1 from C to Perl

     dav_add_response
     dav_buffer_append
     dav_buffer_init
     dav_buffer_place
     dav_buffer_place_mem
     dav_check_bufsize
     dav_close_propdb
     dav_collect_liveprop_uris
     dav_dyn_module_add
     dav_empty_elem
    ...

=item The following map file entry tells XSBuilder that the value of C<res_p> should be returned

     dav_get_resource		| | r, <res_p

The C function

    int dav_get_resource(request_rec *r, dav_resource **res_p) ;

How to call it from Perl

    # get a sub request of the actual document
    $subr = $r -> lookup_uri($uri);

    # get a mod_dav resource object
    my ($err, $resource) =  $subr->get_resource;

=item You can let XSBuilder insert your custom code, for the interface 

If you call C<get_props> from Perl C<glue_dav_get_props> will be called, which can adjust
the arguments and return types as necessary. The actual code for C<glue_dav_get_props> 
will be taken from separate include file.

     dav_get_props 	| glue_
     dav_get_allprops	| glue_


xsinclude\Apache\DAV\PropResult\Apache__DAV__PropResults.h

    dav_get_props_result * dav_glue_get_props(dav_propdb * db, dav_xml_doc *doc)
        {
        dav_get_props_result * result = (dav_get_props_result *)ap_palloc (db -> p, sizeof (dav_get_props_result)) ;
        *result = dav_get_props(db, doc) ;
        return result ;
        }


=item Arguments can be replaced

    MODULE=Apache::Array   PACKAGE=Apache::Array PREFIX=ap_

     ap_make_array      | ap_make_array(r->pool, nelts, elt_size) | request_rec *:r, nelts, elt_size

ap_make_array requires a pool a it's first parameter, we pass the request_rec from Perl and
XSBuilder will take the pool from the request_rec.

=back


=head1 structure map


     MALLOC=strdup:$dest = ($type)strdup($src)
     FREE=strdup:free($src)

     <dav_xml_elem>
       name
       ns
       lang
       first_cdata
       following_cdata
       parent
       next
       first_child
       attr
       last_child
       ns_scope
       propid
       provider
       ns_map
       new
     </dav_xml_elem>

     MALLOC=strdup:$dest = ($type)ap_pstrdup(obj -> pool, $src)

     <array_header>
       pool
       elt_size
       nelts
       nalloc
       elts
       private
     </array_header>

=head2 Create a accessor functions for every element and, if requested, a new method

        $setprop = Apache::DAV::XMLElem -> new ({name => 'prop'}) ;
        $elem    = Apache::DAV::XMLElem -> new ({name => $name, ns => $namespaces}) ; 
        $setprop -> first_child($elem) ;
        $first = $setprop -> first_child ;

=head2 some datatypes, like strings, requires dynamic allocated memory


From _types.map,which conatins a set of standard types

    int             | IV
    int *           | UNDEFINED
    unsigned int    | UV
    signed int      | IV
    long            | IV
    long int        | IV
    unsigned long   | UV
    unsigned        | UV

    char *                   | PV           | | | strdup
    const char *             | PV           | | | strdup
    const char **            | UNDEFINED    
    char const *             | PV           | | | strdup
    unsigned char *          | PV           | | | strdup
    const unsigned char *    | PV           | | | strdup
    ...

=head1 callback maps

Callback maps have the same options a function maps

    # dav_hooks_db -> open
     
     dav_error *(*)(pool * p,const dav_resource * resource,int ro,dav_db * * pdb)  | p, resource, ro=0, <pdb 
    
    
    # dav_hooks_lock -> has_locks
    
     dav_error *(*)(dav_lockdb * lockdb,const dav_resource * resource,int * locks_present)


=head1 Generate the XS files

    use FindBin ;
    use lib ($FindBin::Bin) ;

    require ParseSource ; 
    require WrapXS ; 

    Apache::DAV::WrapXS->run;

=head2 ...and run...

    C:\perl\msrc\davint>perl xsbuilder\xs_generate.pl
    Will use mod_dav in C:\perl\msrc\cvs\mod_dav
    Will use Apache in c:\programme\apache group\apache
    Parse xsbuilder\maps/_types.map...
    Parse xsbuilder\maps/dav_type.map...
    mkdir xs
    writing...xs//typemap
    Parse xsbuilder\maps/dav_functions.map...
    WARNING: Cannot map type int(*)(void * ,const char * ,const char * ) for function ap_table_do
    WARNING: Cannot map type dav_buffer * for function dav_buffer_append
    WARNING: Cannot map type dav_buffer * for function dav_buffer_init
    WARNING: Cannot map type dav_buffer * for function dav_buffer_place
    WARNING: Cannot map type dav_buffer * for function dav_buffer_place_mem
    WARNING: Cannot map type dav_buffer * for function dav_check_bufsize
    WARNING: Cannot map return type int * for function dav_collect_liveprop_uris
    WARNING: Cannot map type dav_resource * * for function dav_ensure_resource_writable
    WARNING: Cannot map type dav_buffer * for function dav_lock_get_activelock
    WARNING: Cannot map type dav_buffer * for function dav_set_bufsize
    WARNING: Cannot map type int * for function dav_xml2text
    struct array_header...
    Parse xsbuilder\maps/dav_structure.map...
         elt_size...
         nelts...
         nalloc...
         elts...
    struct dav_buffer...
    struct dav_datum...
         dptr...
         dsize...
    struct dav_dyn_context...

=head1 Makefile.PL

=head2 We need create a top level Makefile.PL

    use ExtUtils::MakeMaker ();
    
    my $apdir  = '/path/to/apache';
    my $davdir = '/path/to/moddav';

    %MMARGS = (
	       'INC'    => "-I\"$davdir\" -I\"$apdir/include\" -I\"$apdir/os/unix\" -I\"$dir/xs\"  -I\"$dir/xsinclude\"",
	       ) ;


    open FH, ">xs/mmargs.pl" or die "Cannot open xs/mmargs.pl ($!)" ;
    print FH Data::Dumper -> Dump ([\%MMARGS], ['MMARGS']) ;
    close FH ;


    ExtUtils::MakeMaker::WriteMakefile(
        'NAME'    => 'Apache::DAV',
        'VERSION' => '0.13',
        %MMARGS,
    );


=head2 Makefile.PL's for all class are generated automaticly

    C:\perl\msrc\davint>perl Makefile.PL
    Will use Apache in c:\programme\apache group\apache
    Will use mod_dav in C:\perl\msrc\cvs\mod_dav
    Checking if your kit is complete...
    Looks good
    Writing Makefile for Apache::Array
    Writing Makefile for Apache::DAV::Datum
    Writing Makefile for Apache::DAV::DynContext
    Writing Makefile for Apache::DAV::DynHooks
    Writing Makefile for Apache::DAV::DynModule
    Writing Makefile for Apache::DAV::DynProvider
    Writing Makefile for Apache::DAV::Error
    Writing Makefile for Apache::DAV::HooksDb
    Writing Makefile for Apache::DAV::HooksLiveprop
    Writing Makefile for Apache::DAV::HooksLocks
    Writing Makefile for Apache::DAV::HooksRepository
    Writing Makefile for Apache::DAV::IfHeader
    Writing Makefile for Apache::DAV::Lock
    Writing Makefile for Apache::DAV::LockDB
    Writing Makefile for Apache::DAV::LockTokenList
    Writing Makefile for Apache::DAV::LockupResult
    Writing Makefile for Apache::DAV::PropCtx
    Writing Makefile for Apache::DAV::PropsResult
    Writing Makefile for Apache::DAV::Resource
    Writing Makefile for Apache::DAV::Response
    Writing Makefile for Apache::DAV::StateList
    Writing Makefile for Apache::DAV::Text
    Writing Makefile for Apache::DAV::TextHeader
    Writing Makefile for Apache::DAV::WalkerCtx
    Writing Makefile for Apache::DAV::XMLAttr
    Writing Makefile for Apache::DAV::XMLDoc
    Writing Makefile for Apache::DAV::XMLElem
    Writing Makefile for Apache::DAV
    Writing Makefile for Apache::TableEntry
    Writing Makefile for Apache
    Writing Makefile for WrapXS
    Writing Makefile for Apache::DAV

=head2 and now compile...

=head1 How does it go on...

=head2 Generating documentation

XSBuilder already extracts source comments for functions and structures. 
It also parses doxygen comments, which are used in Apache 2.0.
Lyle Brooks has started on automaticly createing POD files from this information.

=head2 Improving callbacks

Callbacks are the main area that needs improvement.

=head2 Bring it back to mod_perl 2.0

=head2 First version will be released just after the conference to CPAN

=head2 Any feedback and help appreciated

=head2 Questions?