perlguts.1

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

\&            /* Get the key from an HE structure and also return
\&               the length of the key string */
\&    SV*    hv_iterval(HV*, HE* entry);
\&            /* Return an SV pointer to the value of the HE
\&               structure */
\&    SV*    hv_iternextsv(HV*, char** key, I32* retlen);
\&            /* This convenience routine combines hv_iternext,
\&               hv_iterkey, and hv_iterval.  The key and retlen
\&               arguments are return values for the key and its
\&               length.  The value is returned in the SV* argument */
.Ve
.PP
If you know the name of a hash variable, you can get a pointer to its \s-1HV\s0
by using the following:
.PP
.Vb 1
\&    HV*  get_hv("package::varname", FALSE);
.Ve
.PP
This returns \s-1NULL\s0 if the variable does not exist.
.PP
The hash algorithm is defined in the \f(CW\*(C`PERL_HASH(hash, key, klen)\*(C'\fR macro:
.PP
.Vb 4
\&    hash = 0;
\&    while (klen\-\-)
\&        hash = (hash * 33) + *key++;
\&    hash = hash + (hash >> 5);                  /* after 5.6 */
.Ve
.PP
The last step was added in version 5.6 to improve distribution of
lower bits in the resulting hash value.
.PP
See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" for more
information on how to use the hash access functions on tied hashes.
.Sh "Hash \s-1API\s0 Extensions"
.IX Subsection "Hash API Extensions"
Beginning with version 5.004, the following functions are also supported:
.PP
.Vb 2
\&    HE*     hv_fetch_ent  (HV* tb, SV* key, I32 lval, U32 hash);
\&    HE*     hv_store_ent  (HV* tb, SV* key, SV* val, U32 hash);
\&
\&    bool    hv_exists_ent (HV* tb, SV* key, U32 hash);
\&    SV*     hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
\&
\&    SV*     hv_iterkeysv  (HE* entry);
.Ve
.PP
Note that these functions take \f(CW\*(C`SV*\*(C'\fR keys, which simplifies writing
of extension code that deals with hash structures.  These functions
also allow passing of \f(CW\*(C`SV*\*(C'\fR keys to \f(CW\*(C`tie\*(C'\fR functions without forcing
you to stringify the keys (unlike the previous set of functions).
.PP
They also return and accept whole hash entries (\f(CW\*(C`HE*\*(C'\fR), making their
use more efficient (since the hash number for a particular string
doesn't have to be recomputed every time).  See perlapi for detailed
descriptions.
.PP
The following macros must always be used to access the contents of hash
entries.  Note that the arguments to these macros must be simple
variables, since they may get evaluated more than once.  See
perlapi for detailed descriptions of these macros.
.PP
.Vb 6
\&    HePV(HE* he, STRLEN len)
\&    HeVAL(HE* he)
\&    HeHASH(HE* he)
\&    HeSVKEY(HE* he)
\&    HeSVKEY_force(HE* he)
\&    HeSVKEY_set(HE* he, SV* sv)
.Ve
.PP
These two lower level macros are defined, but must only be used when
dealing with keys that are not \f(CW\*(C`SV*\*(C'\fRs:
.PP
.Vb 2
\&    HeKEY(HE* he)
\&    HeKLEN(HE* he)
.Ve
.PP
Note that both \f(CW\*(C`hv_store\*(C'\fR and \f(CW\*(C`hv_store_ent\*(C'\fR do not increment the
reference count of the stored \f(CW\*(C`val\*(C'\fR, which is the caller's responsibility.
If these functions return a \s-1NULL\s0 value, the caller will usually have to
decrement the reference count of \f(CW\*(C`val\*(C'\fR to avoid a memory leak.
.Sh "AVs, HVs and undefined values"
.IX Subsection "AVs, HVs and undefined values"
Sometimes you have to store undefined values in AVs or HVs. Although
this may be a rare case, it can be tricky. That's because you're
used to using \f(CW&PL_sv_undef\fR if you need an undefined \s-1SV\s0.
.PP
For example, intuition tells you that this \s-1XS\s0 code:
.PP
.Vb 2
\&    AV *av = newAV();
\&    av_store( av, 0, &PL_sv_undef );
.Ve
.PP
is equivalent to this Perl code:
.PP
.Vb 2
\&    my @av;
\&    $av[0] = undef;
.Ve
.PP
Unfortunately, this isn't true. AVs use \f(CW&PL_sv_undef\fR as a marker
for indicating that an array element has not yet been initialized.
Thus, \f(CW\*(C`exists $av[0]\*(C'\fR would be true for the above Perl code, but
false for the array generated by the \s-1XS\s0 code.
.PP
Other problems can occur when storing \f(CW&PL_sv_undef\fR in HVs:
.PP
.Vb 1
\&    hv_store( hv, "key", 3, &PL_sv_undef, 0 );
.Ve
.PP
This will indeed make the value \f(CW\*(C`undef\*(C'\fR, but if you try to modify
the value of \f(CW\*(C`key\*(C'\fR, you'll get the following error:
.PP
.Vb 1
\&    Modification of non\-creatable hash value attempted
.Ve
.PP
In perl 5.8.0, \f(CW&PL_sv_undef\fR was also used to mark placeholders
in restricted hashes. This caused such hash entries not to appear
when iterating over the hash or when checking for the keys
with the \f(CW\*(C`hv_exists\*(C'\fR function.
.PP
You can run into similar problems when you store \f(CW&PL_sv_true\fR or
\&\f(CW&PL_sv_false\fR into AVs or HVs. Trying to modify such elements
will give you the following error:
.PP
.Vb 1
\&    Modification of a read\-only value attempted
.Ve
.PP
To make a long story short, you can use the special variables
\&\f(CW&PL_sv_undef\fR, \f(CW&PL_sv_true\fR and \f(CW&PL_sv_false\fR with AVs and
HVs, but you have to make sure you know what you're doing.
.PP
Generally, if you want to store an undefined value in an \s-1AV\s0
or \s-1HV\s0, you should not use \f(CW&PL_sv_undef\fR, but rather create a
new undefined value using the \f(CW\*(C`newSV\*(C'\fR function, for example:
.PP
.Vb 2
\&    av_store( av, 42, newSV(0) );
\&    hv_store( hv, "foo", 3, newSV(0), 0 );
.Ve
.Sh "References"
.IX Subsection "References"
References are a special type of scalar that point to other data types
(including references).
.PP
To create a reference, use either of the following functions:
.PP
.Vb 2
\&    SV* newRV_inc((SV*) thing);
\&    SV* newRV_noinc((SV*) thing);
.Ve
.PP
The \f(CW\*(C`thing\*(C'\fR argument can be any of an \f(CW\*(C`SV*\*(C'\fR, \f(CW\*(C`AV*\*(C'\fR, or \f(CW\*(C`HV*\*(C'\fR.  The
functions are identical except that \f(CW\*(C`newRV_inc\*(C'\fR increments the reference
count of the \f(CW\*(C`thing\*(C'\fR, while \f(CW\*(C`newRV_noinc\*(C'\fR does not.  For historical
reasons, \f(CW\*(C`newRV\*(C'\fR is a synonym for \f(CW\*(C`newRV_inc\*(C'\fR.
.PP
Once you have a reference, you can use the following macro to dereference
the reference:
.PP
.Vb 1
\&    SvRV(SV*)
.Ve
.PP
then call the appropriate routines, casting the returned \f(CW\*(C`SV*\*(C'\fR to either an
\&\f(CW\*(C`AV*\*(C'\fR or \f(CW\*(C`HV*\*(C'\fR, if required.
.PP
To determine if an \s-1SV\s0 is a reference, you can use the following macro:
.PP
.Vb 1
\&    SvROK(SV*)
.Ve
.PP
To discover what type of value the reference refers to, use the following
macro and then check the return value.
.PP
.Vb 1
\&    SvTYPE(SvRV(SV*))
.Ve
.PP
The most useful types that will be returned are:
.PP
.Vb 9
\&    SVt_IV    Scalar
\&    SVt_NV    Scalar
\&    SVt_PV    Scalar
\&    SVt_RV    Scalar
\&    SVt_PVAV  Array
\&    SVt_PVHV  Hash
\&    SVt_PVCV  Code
\&    SVt_PVGV  Glob (possible a file handle)
\&    SVt_PVMG  Blessed or Magical Scalar
\&
\&    See the sv.h header file for more details.
.Ve
.Sh "Blessed References and Class Objects"
.IX Subsection "Blessed References and Class Objects"
References are also used to support object-oriented programming.  In perl's
\&\s-1OO\s0 lexicon, an object is simply a reference that has been blessed into a
package (or class).  Once blessed, the programmer may now use the reference
to access the various methods in the class.
.PP
A reference can be blessed into a package with the following function:
.PP
.Vb 1
\&    SV* sv_bless(SV* sv, HV* stash);
.Ve
.PP
The \f(CW\*(C`sv\*(C'\fR argument must be a reference value.  The \f(CW\*(C`stash\*(C'\fR argument
specifies which class the reference will belong to.  See
\&\*(L"Stashes and Globs\*(R" for information on converting class names into stashes.
.PP
/* Still under construction */
.PP
Upgrades rv to reference if not already one.  Creates new \s-1SV\s0 for rv to
point to.  If \f(CW\*(C`classname\*(C'\fR is non-null, the \s-1SV\s0 is blessed into the specified
class.  \s-1SV\s0 is returned.
.PP
.Vb 1
\&        SV* newSVrv(SV* rv, const char* classname);
.Ve
.PP
Copies integer, unsigned integer or double into an \s-1SV\s0 whose reference is \f(CW\*(C`rv\*(C'\fR.  \s-1SV\s0 is blessed
if \f(CW\*(C`classname\*(C'\fR is non-null.
.PP
.Vb 3
\&        SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
\&        SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
\&        SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
.Ve
.PP
Copies the pointer value (\fIthe address, not the string!\fR) into an \s-1SV\s0 whose
reference is rv.  \s-1SV\s0 is blessed if \f(CW\*(C`classname\*(C'\fR is non-null.
.PP
.Vb 1
\&        SV* sv_setref_pv(SV* rv, const char* classname, PV iv);
.Ve
.PP
Copies string into an \s-1SV\s0 whose reference is \f(CW\*(C`rv\*(C'\fR.  Set length to 0 to let
Perl calculate the string length.  \s-1SV\s0 is blessed if \f(CW\*(C`classname\*(C'\fR is non-null.
.PP
.Vb 1
\&        SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);
.Ve
.PP
Tests whether the \s-1SV\s0 is blessed into the specified class.  It does not
check inheritance relationships.
.PP
.Vb 1
\&        int  sv_isa(SV* sv, const char* name);
.Ve
.PP
Tests whether the \s-1SV\s0 is a reference to a blessed object.
.PP
.Vb 1
\&        int  sv_isobject(SV* sv);
.Ve
.PP
Tests whether the \s-1SV\s0 is derived from the specified class. \s-1SV\s0 can be either
a reference to a blessed object or a string containing a class name. This
is the function implementing the \f(CW\*(C`UNIVERSAL::isa\*(C'\fR functionality.
.PP
.Vb 1
\&        bool sv_derived_from(SV* sv, const char* name);
.Ve
.PP
To check if you've got an object derived from a specific class you have
to write:
.PP
.Vb 1
\&        if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
.Ve
.Sh "Creating New Variables"
.IX Subsection "Creating New Variables"
To create a new Perl variable with an undef value which can be accessed from
your Perl script, use the following routines, depending on the variable type.
.PP
.Vb 3
\&    SV*  get_sv("package::varname", TRUE);
\&    AV*  get_av("package::varname", TRUE);
\&    HV*  get_hv("package::varname", TRUE);
.Ve
.PP
Notice the use of \s-1TRUE\s0 as the second parameter.  The new variable can now
be set, using the routines appropriate to the data type.
.PP
There are additional macros whose values may be bitwise \s-1OR\s0'ed with the
\&\f(CW\*(C`TRUE\*(C'\fR argument to enable certain extra features.  Those bits are:
.IP "\s-1GV_ADDMULTI\s0" 4
.IX Item "GV_ADDMULTI"
Marks the variable as multiply defined, thus preventing the:
.Sp
.Vb 1
\&  Name <varname> used only once: possible typo
.Ve
.Sp
warning.
.IP "\s-1GV_ADDWARN\s0" 4
.IX Item "GV_ADDWARN"
Issues the warning:
.Sp
.Vb 1