extutils::xsbuilder.3

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

\&    perl \-MMyClass::WrapXS \-e \*(AqMyClass::WrapXS\->run\*(Aq
.Ve
.PP
XSBuilder will create the \s-1XS\s0, pm and Makefile.PL files for every module that 
is mentioned in the maps. The result is placed as a directory hierarchy under
WrapXS. To control the content of the \f(CW\*(C`Makefile.PL\*(C'\fR and the \f(CW\*(C`pm\*(C'\fR file, you
can override the \f(CW\*(C`makefilepl_text\*(C'\fR and \f(CW\*(C`pm_text\*(C'\fR methods. You can include
additional code in the \s-1XS\s0 files by writing an include file which is included
at the top of the \s-1XS\s0 file. This file can contain helper functions that can't
be automatically generated. The files must be placed under the \f(CW\*(C`xs\*(C'\fR
directory, with the correct path and name. For example, to have a header file
included for the module Apache::DAV, create a file named
\&\f(CW\*(C`xs/Apache/DAV/Apache_\|_DAV.h\*(C'\fR. The same can be done for inclusion in the pm
file. Following the example above, the file name would be 
\&\f(CW\*(C`xs/Apache/DAV/DAV_pm\*(C'\fR.
.SH "Format of the map files"
.IX Header "Format of the map files"
For all map files blank lines are ignored and lines starting with a \f(CW\*(C`#\*(C'\fR are
treated as comments and are also ignored.
.Sh "Types map file"
.IX Subsection "Types map file"
Contains the mapping from C type to Perl classes.
.PP
Format is the name of the C type followed by the name of the Perl class
or the \s-1XS\s0 type specifier, separated by a \f(CW\*(C`|\*(C'\fR. Example:
.PP
.Vb 2
\&    int                 | IV
\&    struct request_rec  | Apache::RequestRec
.Ve
.PP
If you have a Perl class with a single-level namespace (e.g. Apache) you need
to postfix it with two colons (e.g. \*(L"Apache::\*(R"). When both a typedef and a
structure share the same name, structures must be written as with a \*(L"struct \*(R"
prefix (e.g. \*(L"struct foo\*(R".) Addionally, you can give the id for the typemap if
you need a special conversion and one or more other names for the struct:
.PP
.Vb 1
\&    struct request_rec  | Apache::RequestRec | T_APACHEOBJ | r
.Ve
.PP
An optional fifth parameter specifies that the data needs to be copied
when assigned to a struct member and selects the way how memory is allocated:
.PP
.Vb 1
\&    char *   | PV | | | strdup
.Ve
.PP
The actual code for memory allocation is provided inside the structure map,
for example:
.PP
.Vb 2
\&    MALLOC=strdup:$dest = ($type)ap_pstrdup(obj \-> pool, $src)
\&    MALLOC=malloc:ap_palloc(obj \-> pool, $src, sizeof($type)) ; memcpy($dest,$src,sizeof($type))
.Ve
.PP
This gives two ways to allocate memory and copy the data into it. The fifth
parameter in the type map selects which of these two should be used. \f(CW$src\fR,
\&\f(CW$dest\fR and \f(CW$type\fR are replaced by the source, the destination and the type.
\&\f(CW\*(C`obj\*(C'\fR is a pointer to the C\-structure.
.PP
\fISpecial Types\fR
.IX Subsection "Special Types"
.IP "String, \s-1PV\s0 and PVnull" 4
.IX Item "String, PV and PVnull"
A string is represented in C as a pointer to an null terminated range of
characters. In Perl the it is called \f(CW\*(C`PV\*(C'\fR (pointer value). When converting
a Perl \f(CW\*(C`undef\*(C'\fR to a C string Perl by default converts it to an empty string.
While this is save, this is not always what is required, because many
C interfaces treat \s-1NULL\s0 as a special case. For this reason the \f(CW\*(C`PVnull\*(C'\fR type
is introduced, which converts \f(CW\*(C`undef\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR and \f(CW\*(C`NULL\*(C'\fR to \f(CW\*(C`undef\*(C'\fR.
.Sp
To make it work you need the following line in your type map file:
.Sp
.Vb 1
\&        PVnull          | PVnull | | | strdup
.Ve
.Sp
Now you can defines any type, structure memeber or function argument
as type \f(CW\*(C`PVnull\*(C'\fR.
.Sh "Functions map file"
.IX Subsection "Functions map file"
Contains the mapping from C functions to Perl functions. This can be used to 
reorder arguments, tell XSBuilder which arguments are return values, and in
which Perl package the function will be created.
.PP
There are some directives which affect the function mappings that follow it.
Each directive may appear in the file more than once.
.IP "\s-1MODULE\s0" 4
.IX Item "MODULE"
the module name (file name) where the function should be defined, e.g.
.Sp
.Vb 1
\&    MODULE=Apache::Connection
.Ve
.Sp
will define the functions that follow in files named Apache/Connection.{pm,xs}
.IP "\s-1PACKAGE\s0" 4
.IX Item "PACKAGE"
The name of the package that functions are defined in. If undefined, \s-1PACKAGE\s0
defaults to the value of \s-1MODULE\s0. A value of 'guess' indicates that package
name should be guessed based on first argument found that maps to a Perl
class. Falls back on the prefix (ap_ \-> Apache, apr_ \-> \s-1APR\s0).
.IP "\s-1PREFIX\s0" 4
.IX Item "PREFIX"
The prefix to be stripped from C functions when creating the \s-1XS\s0 stubs.
Defaults to the value of \s-1PACKAGE\s0, converted to C naming convention. For
example,
.Sp
.Vb 1
\&    PREFIX=APR::Base64
.Ve
.Sp
will strip \f(CW\*(C`apr_base64_\*(C'\fR from the C functions. If the prefix does not match,
it defaults to \f(CW\*(C`ap_\*(C'\fR or \f(CW\*(C`apr_\*(C'\fR.
.PP
\&\fB\s-1NOTE:\s0\fR You must have at least one \f(CW\*(C`MODULE\*(C'\fR definition
otherwise all functions will be ignored.
.PP
The format of entries is:
.PP
.Vb 1
\&    C function name | dispatch function name (dispatch argspec) | argspec | Perl alias
.Ve
.PP
The \f(CW\*(C`dispatch function name\*(C'\fR (the C function that is actually called)
defaults to C function name. If the dispatch function name is just a prefix
(mpxs_, \s-1MPXS_\s0), the \f(CW\*(C`C function name\*(C'\fR is appended to it. The return type may
be specified before the \f(CW\*(C`C function name\*(C'\fR, and defaults to the \f(CW\*(C`return_type\*(C'\fR
in the \f(CW\*(C`{foo}::FunctionTable\*(C'\fR module generated by the \f(CW\*(C`ParseSource\*(C'\fR module.
.PP
The \f(CW\*(C`dispatch argspec\*(C'\fR is optional. If supplied, it can be used to pass
different parameters to the dispatch function then to the \s-1XS\s0 function. If the
function name begins with \f(CW\*(C`DEFINE_\*(C'\fR, a new function is defined (for defining
functions that are not parsed from the source). \f(CW\*(C`argspec\*(C'\fR must be supplied.
\&\f(CW\*(C`DEFINE_\*(C'\fR is not included in the generated function name.
.PP
The \f(CW\*(C`argspec\*(C'\fR defaults to arguments in \f(CW\*(C`{foo}::FunctionTable\*(C'\fR, as generated
by the \f(CW\*(C`ParseSource\*(C'\fR module. Argument types can be specified to override
those in the \f(CW\*(C`{foo}::FunctionTable\*(C'\fR. Default values can also be specified,
e.g. arg=default_value
.PP
For example:
  ap_get_client_block   | mpxs_ | r, \s-1SV\s0 *:buffer, bufsiz
  ap_setup_client_block |       | r, read_policy=REQUEST_CHUNKED_ERROR
  ap_make_array      | ap_make_array(r\->pool, nelts, elt_size) | request_rec *:r, nelts, elt_size
.PP
argspec of '...' indicates passthru, calling the function with
.PP
.Vb 1
\&    (aTHX_ I32 items, SP **sp, SV **MARK)
.Ve
.PP
To mark an argument as return only you can prefix it with < e.g.
.PP
.Vb 1
\&    dav_open_lockdb | | r, ro, <lockdb
.Ve
.PP
will be called as ($error get the return value of the C function)
.PP
.Vb 1
\&    ($error, $lockdb) = $r \-> open_lockdb (0) ;
.Ve
.PP
The return argument (e.g. lockdb) will always be passed by address 
to the function.
.PP
The function alias, if defined, will be created in the current \f(CW\*(C`PACKAGE\*(C'\fR.
.PP
Function names on lines that do not begin with a word character or a single
space are skipped. Function names can be prefixed with the following symbols:
.PP
.Vb 5
\&    \*(Aq!\*(Aq => \*(Aqdisabled or not yet implemented\*(Aq,
\&    \*(Aq~\*(Aq => \*(Aqimplemented but not auto\-generated\*(Aq,
\&    \*(Aq\-\*(Aq => \*(Aqlikely never be available to Perl\*(Aq,
\&    \*(Aq>\*(Aq => \*(Aq"private" to your C library\*(Aq,
\&    \*(Aq?\*(Aq => \*(Aqunclassified\*(Aq,
.Ve
.Sh "Structures map file"
.IX Subsection "Structures map file"
Contains the mapping from C structures to Perl classes and defines the members
for which access methods should be created. A \f(CW\*(C`new\*(C'\fR method may be specified,
if desired. The format looks like the following:
.PP
.Vb 5
\&    <struct_name>
\&      member1
\&      member2
\&      new
\&    </struct_name>
.Ve
.PP
An optional module name can be given, to specify in which module the code
should be placed. To place the structure in My::Module, for example, specify:
.PP
.Vb 1
\&    <struct_name MODULE=My::Module>
.Ve
.PP
For all members that are listed here, XSBuilder will generate an access method
to read and write it's content. If you want to name the perl access method
differently than the C member, you can write
.PP
.Vb 1
\&   cMemberValue | member_value | type
.Ve
.PP
this will map the \f(CW\*(C`cMemberValue\*(C'\fR structure member to the access function 
\&\f(CW\*(C`member_value\*(C'\fR. The default is to use the same name in Perl as in C.
As third argument you can give a typename. This defaults to the type of the 
variable. It can be used to specify a different type, for special conversion needs.
(e.g. \s-1PV\s0 versus PVnull)
If you give the \f(CW\*(C`new\*(C'\fR member, XSBuilder will create a new method for that
class, which can be used to create a new instance and initialize it with data.
.Sh "Callbacks map file"
.IX Subsection "Callbacks map file"
The format of entries is:
.PP
.Vb 1
\&    C function name | argspec
.Ve
.PP
The content is the same as function map, it but contains the callbacks.
.SH "Additional generated methods"
.IX Header "Additional generated methods"
For structures, XSBuilder will generate two additional methods: \f(CW\*(C`new\*(C'\fR, and
\&\f(CW\*(C`init_callbacks\*(C'\fR.
.Sh "new ($initialvalue)"
.IX Subsection "new ($initialvalue)"
With \f(CW\*(C`new\*(C'\fR you can create a new Perl object for an C structure. Optionally,
you can pass either a hashref with initial data, or another object, who's
data will be copied into the new object.
.Sh "init_callbacks"
.IX Subsection "init_callbacks"
\&\f(CW\*(C`init_callbacks\*(C'\fR should be called during object initialization. It will fill
in all callback members of a structure with pointers that cause a method call
into the object, when the callback is called from C.
.PP
You can call it either with
.PP
.Vb 1
\&    $obj \-> init_callbacks
.Ve
.PP
or
.PP
.Vb 1
\&    MyModule \-> init_callbacks ($obj) ;
.Ve
.SH "Callbacks"
.IX Header "Callbacks"
A callback which is part of a structure will cause a call to the method with
the same name as the structure member, prefixed with \f(CW\*(C`cb_\*(C'\fR. For example, if
you have a structure member named \f(CW\*(C`open\*(C'\fR, then the Perl method \f(CW\*(C`cb_open\*(C'\fR
will be called whenever the C code calls the callback.
.PP
If you want to call the callback on your own you need to call the method which
is called like the structure member, e.g. \f(CW\*(C`open\*(C'\fR.
.PP
\&\s-1NOTE:\s0 You need to call \f(CW\*(C`init_callbacks\*(C'\fR during your method initialzation to
be able to call callbacks.