storable.3

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

deserialization is done through \f(CW\*(C`eval\*(C'\fR, which is dangerous if the
Storable file contains malicious data. You can set \f(CW$Storable::Eval\fR
to a subroutine reference which would be used instead of \f(CW\*(C`eval\*(C'\fR. See
below for an example using a Safe compartment for deserialization
of \s-1CODE\s0 references.
.PP
If \f(CW$Storable::Deparse\fR and/or \f(CW$Storable::Eval\fR are set to false
values, then the value of \f(CW$Storable::forgive_me\fR (see below) is
respected while serializing and deserializing.
.SH "FORWARD COMPATIBILITY"
.IX Header "FORWARD COMPATIBILITY"
This release of Storable can be used on a newer version of Perl to
serialize data which is not supported by earlier Perls.  By default,
Storable will attempt to do the right thing, by \f(CW\*(C`croak()\*(C'\fRing if it
encounters data that it cannot deserialize.  However, the defaults
can be changed as follows:
.IP "utf8 data" 4
.IX Item "utf8 data"
Perl 5.6 added support for Unicode characters with code points > 255,
and Perl 5.8 has full support for Unicode characters in hash keys.
Perl internally encodes strings with these characters using utf8, and
Storable serializes them as utf8.  By default, if an older version of
Perl encounters a utf8 value it cannot represent, it will \f(CW\*(C`croak()\*(C'\fR.
To change this behaviour so that Storable deserializes utf8 encoded
values as the string of bytes (effectively dropping the \fIis_utf8\fR flag)
set \f(CW$Storable::drop_utf8\fR to some \f(CW\*(C`TRUE\*(C'\fR value.  This is a form of
data loss, because with \f(CW$drop_utf8\fR true, it becomes impossible to tell
whether the original data was the Unicode string, or a series of bytes
that happen to be valid utf8.
.IP "restricted hashes" 4
.IX Item "restricted hashes"
Perl 5.8 adds support for restricted hashes, which have keys
restricted to a given set, and can have values locked to be read only.
By default, when Storable encounters a restricted hash on a perl
that doesn't support them, it will deserialize it as a normal hash,
silently discarding any placeholder keys and leaving the keys and
all values unlocked.  To make Storable \f(CW\*(C`croak()\*(C'\fR instead, set
\&\f(CW$Storable::downgrade_restricted\fR to a \f(CW\*(C`FALSE\*(C'\fR value.  To restore
the default set it back to some \f(CW\*(C`TRUE\*(C'\fR value.
.IP "files from future versions of Storable" 4
.IX Item "files from future versions of Storable"
Earlier versions of Storable would immediately croak if they encountered
a file with a higher internal version number than the reading Storable
knew about.  Internal version numbers are increased each time new data
types (such as restricted hashes) are added to the vocabulary of the file
format.  This meant that a newer Storable module had no way of writing a
file readable by an older Storable, even if the writer didn't store newer
data types.
.Sp
This version of Storable will defer croaking until it encounters a data
type in the file that it does not recognize.  This means that it will
continue to read files generated by newer Storable modules which are careful
in what they write out, making it easier to upgrade Storable modules in a
mixed environment.
.Sp
The old behaviour of immediate croaking can be re-instated by setting
\&\f(CW$Storable::accept_future_minor\fR to some \f(CW\*(C`FALSE\*(C'\fR value.
.PP
All these variables have no effect on a newer Perl which supports the
relevant feature.
.SH "ERROR REPORTING"
.IX Header "ERROR REPORTING"
Storable uses the \*(L"exception\*(R" paradigm, in that it does not try to workaround
failures: if something bad happens, an exception is generated from the
caller's perspective (see Carp and \f(CW\*(C`croak()\*(C'\fR).  Use eval {} to trap
those exceptions.
.PP
When Storable croaks, it tries to report the error via the \f(CW\*(C`logcroak()\*(C'\fR
routine from the \f(CW\*(C`Log::Agent\*(C'\fR package, if it is available.
.PP
Normal errors are reported by having \fIstore()\fR or \fIretrieve()\fR return \f(CW\*(C`undef\*(C'\fR.
Such errors are usually I/O errors (or truncated stream errors at retrieval).
.SH "WIZARDS ONLY"
.IX Header "WIZARDS ONLY"
.Sh "Hooks"
.IX Subsection "Hooks"
Any class may define hooks that will be called during the serialization
and deserialization process on objects that are instances of that class.
Those hooks can redefine the way serialization is performed (and therefore,
how the symmetrical deserialization should be conducted).
.PP
Since we said earlier:
.PP
.Vb 1
\&    dclone(.) = thaw(freeze(.))
.Ve
.PP
everything we say about hooks should also hold for deep cloning. However,
hooks get to know whether the operation is a mere serialization, or a cloning.
.PP
Therefore, when serializing hooks are involved,
.PP
.Vb 1
\&    dclone(.) <> thaw(freeze(.))
.Ve
.PP
Well, you could keep them in sync, but there's no guarantee it will always
hold on classes somebody else wrote.  Besides, there is little to gain in
doing so: a serializing hook could keep only one attribute of an object,
which is probably not what should happen during a deep cloning of that
same object.
.PP
Here is the hooking interface:
.ie n .IP """STORABLE_freeze""\fR \fIobj\fR, \fIcloning" 4
.el .IP "\f(CWSTORABLE_freeze\fR \fIobj\fR, \fIcloning\fR" 4
.IX Item "STORABLE_freeze obj, cloning"
The serializing hook, called on the object during serialization.  It can be
inherited, or defined in the class itself, like any other method.
.Sp
Arguments: \fIobj\fR is the object to serialize, \fIcloning\fR is a flag indicating
whether we're in a \fIdclone()\fR or a regular serialization via \fIstore()\fR or \fIfreeze()\fR.
.Sp
Returned value: A \s-1LIST\s0 \f(CW\*(C`($serialized, $ref1, $ref2, ...)\*(C'\fR where \f(CW$serialized\fR
is the serialized form to be used, and the optional \f(CW$ref1\fR, \f(CW$ref2\fR, etc... are
extra references that you wish to let the Storable engine serialize.
.Sp
At deserialization time, you will be given back the same \s-1LIST\s0, but all the
extra references will be pointing into the deserialized structure.
.Sp
The \fBfirst time\fR the hook is hit in a serialization flow, you may have it
return an empty list.  That will signal the Storable engine to further
discard that hook for this class and to therefore revert to the default
serialization of the underlying Perl data.  The hook will again be normally
processed in the next serialization.
.Sp
Unless you know better, serializing hook should always say:
.Sp
.Vb 5
\&    sub STORABLE_freeze {
\&        my ($self, $cloning) = @_;
\&        return if $cloning;         # Regular default serialization
\&        ....
\&    }
.Ve
.Sp
in order to keep reasonable \fIdclone()\fR semantics.
.ie n .IP """STORABLE_thaw""\fR \fIobj\fR, \fIcloning\fR, \fIserialized, ..." 4
.el .IP "\f(CWSTORABLE_thaw\fR \fIobj\fR, \fIcloning\fR, \fIserialized\fR, ..." 4
.IX Item "STORABLE_thaw obj, cloning, serialized, ..."
The deserializing hook called on the object during deserialization.
But wait: if we're deserializing, there's no object yet... right?
.Sp
Wrong: the Storable engine creates an empty one for you.  If you know Eiffel,
you can view \f(CW\*(C`STORABLE_thaw\*(C'\fR as an alternate creation routine.
.Sp
This means the hook can be inherited like any other method, and that
\&\fIobj\fR is your blessed reference for this particular instance.
.Sp
The other arguments should look familiar if you know \f(CW\*(C`STORABLE_freeze\*(C'\fR:
\&\fIcloning\fR is true when we're part of a deep clone operation, \fIserialized\fR
is the serialized string you returned to the engine in \f(CW\*(C`STORABLE_freeze\*(C'\fR,
and there may be an optional list of references, in the same order you gave
them at serialization time, pointing to the deserialized objects (which
have been processed courtesy of the Storable engine).
.Sp
When the Storable engine does not find any \f(CW\*(C`STORABLE_thaw\*(C'\fR hook routine,
it tries to load the class by requiring the package dynamically (using
the blessed package name), and then re-attempts the lookup.  If at that
time the hook cannot be located, the engine croaks.  Note that this mechanism
will fail if you define several classes in the same file, but perlmod
warned you.
.Sp
It is up to you to use this information to populate \fIobj\fR the way you want.
.Sp
Returned value: none.
.ie n .IP """STORABLE_attach""\fR \fIclass\fR, \fIcloning\fR, \fIserialized" 4
.el .IP "\f(CWSTORABLE_attach\fR \fIclass\fR, \fIcloning\fR, \fIserialized\fR" 4
.IX Item "STORABLE_attach class, cloning, serialized"
While \f(CW\*(C`STORABLE_freeze\*(C'\fR and \f(CW\*(C`STORABLE_thaw\*(C'\fR are useful for classes where
each instance is independent, this mechanism has difficulty (or is
incompatible) with objects that exist as common process-level or
system-level resources, such as singleton objects, database pools, caches
or memoized objects.
.Sp
The alternative \f(CW\*(C`STORABLE_attach\*(C'\fR method provides a solution for these
shared objects. Instead of \f(CW\*(C`STORABLE_freeze\*(C'\fR \-\-> \f(CW\*(C`STORABLE_thaw\*(C'\fR,
you implement \f(CW\*(C`STORABLE_freeze\*(C'\fR \-\-> \f(CW\*(C`STORABLE_attach\*(C'\fR instead.
.Sp
Arguments: \fIclass\fR is the class we are attaching to, \fIcloning\fR is a flag
indicating whether we're in a \fIdclone()\fR or a regular de-serialization via
\&\fIthaw()\fR, and \fIserialized\fR is the stored string for the resource object.
.Sp
Because these resource objects are considered to be owned by the entire
process/system, and not the \*(L"property\*(R" of whatever is being serialized,
no references underneath the object should be included in the serialized
string. Thus, in any class that implements \f(CW\*(C`STORABLE_attach\*(C'\fR, the
\&\f(CW\*(C`STORABLE_freeze\*(C'\fR method cannot return any references, and \f(CW\*(C`Storable\*(C'\fR
will throw an error if \f(CW\*(C`STORABLE_freeze\*(C'\fR tries to return references.
.Sp
All information required to \*(L"attach\*(R" back to the shared resource object
\&\fBmust\fR be contained \fBonly\fR in the \f(CW\*(C`STORABLE_freeze\*(C'\fR return string.
Otherwise, \f(CW\*(C`STORABLE_freeze\*(C'\fR behaves as normal for \f(CW\*(C`STORABLE_attach\*(C'\fR
classes.
.Sp
Because \f(CW\*(C`STORABLE_attach\*(C'\fR is passed the class (rather than an object),
it also returns the object directly, rather than modifying the passed
object.
.Sp
Returned value: object of type \f(CW\*(C`class\*(C'\fR
.Sh "Predicates"
.IX Subsection "Predicates"
Predicates are not exportable.  They must be called by explicitly prefixing
them with the Storable package name.
.ie n .IP """Storable::last_op_in_netorder""" 4
.el .IP "\f(CWStorable::last_op_in_netorder\fR" 4
.IX Item "Storable::last_op_in_netorder"
The \f(CW\*(C`Storable::last_op_in_netorder()\*(C'\fR predicate will tell you whether
network order was used in the last store or retrieve operation.  If you
don't know how to use this, just forget about it.
.ie n .IP """Storable::is_storing""" 4
.el .IP "\f(CWStorable::is_storing\fR" 4
.IX Item "Storable::is_storing"
Returns true if within a store operation (via STORABLE_freeze hook).
.ie n .IP """Storable::is_retrieving""" 4
.el .IP "\f(CWStorable::is_retrieving\fR" 4
.IX Item "Storable::is_retrieving"
Returns true if within a retrieve operation (via STORABLE_thaw hook).
.Sh "Recursion"
.IX Subsection "Recursion"
With hooks comes the ability to recurse back to the Storable engine.
Indeed, hooks are regular Perl code, and Storable is convenient when
it comes to serializing and deserializing things, so why not use it
to handle the serialization string?
.PP
There are a few things you need to know, however:
.IP "\(bu" 4
You can create endless loops if the things you serialize via \fIfreeze()\fR
(for instance) point back to the object we're trying to serialize in
the hook.
.IP "\(bu" 4
Shared references among objects will not stay shared: if we're serializing
the list of object [A, C] where both object A and C refer to the \s-1SAME\s0 object
B, and if there is a serializing hook in A that says freeze(B), then when
deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D,
a deep clone of B'.  The topology was not preserved.
.PP
That's why \f(CW\*(C`STORABLE_freeze\*(C'\fR lets you provide a list of references
to serialize.  The engine guarantees that those will be serialized in the
same context as the other objects, and therefore that shared objects will
stay shared.
.PP
In the above [A, C] example, the \f(CW\*(C`STORABLE_freeze\*(C'\fR hook could return:
.PP
.Vb 1
\&        ("something", $self\->{B})
.Ve
.PP
and the B part would be serialized by the engine.  In \f(CW\*(C`STORABLE_thaw\*(C'\fR, you
would get back the reference to the B' object, deserialized for you.
.PP
Therefore, recursion should normally be avoided, but is nonetheless supported.
.Sh "Deep Cloning"
.IX Subsection "Deep Cloning"
There is a Clone module available on \s-1CPAN\s0 which implements deep cloning
natively, i.e. without freezing to memory and thawing the result.  It is
aimed to replace Storable's \fIdclone()\fR some day.  However, it does not currently
support Storable hooks to redefine the way deep cloning is performed.
.SH "Storable magic"
.IX Header "Storable magic"
Yes, there's a lot of that :\-) But more precisely, in \s-1UNIX\s0 systems
there's a utility called \f(CW\*(C`file\*(C'\fR, which recognizes data files based on
their contents (usually their first few bytes).  For this to work,
a certain file called \fImagic\fR needs to taught about the \fIsignature\fR
of the data.  Where that configuration file lives depends on the \s-1UNIX\s0
flavour; often it's something like \fI/usr/share/misc/magic\fR or
\&\fI/etc/magic\fR.  Your system administrator needs to do the updating of
the \fImagic\fR file.  The necessary signature information is output to
\&\s-1STDOUT\s0 by invoking \fIStorable::show_file_magic()\fR.  Note that the \s-1GNU\s0
implementation of the \f(CW\*(C`file\*(C'\fR utility, version 3.38 or later,
is expected to contain support for recognising Storable files
out-of-the-box, in addition to other kinds of Perl files.
.PP
You can also use the following functions to extract the file header
information from Storable images:
.ie n .IP "$info\fR = Storable::file_magic( \f(CW$filename )" 4
.el .IP "\f(CW$info\fR = Storable::file_magic( \f(CW$filename\fR )" 4
.IX Item "$info = Storable::file_magic( $filename )"
If the given file is a Storable image return a hash describing it.  If
the file is readable, but not a Storable image return \f(CW\*(C`undef\*(C'\fR.  If
the file does not exist or is unreadable then croak.
.Sp
The hash returned has the following elements:
.RS 4
.ie n .IP """version""" 4
.el .IP "\f(CWversion\fR" 4
.IX Item "version"
This returns the file format version.  It is a string like \*(L"2.7\*(R".
.Sp
Note that this version number is not the same as the version number of
the Storable module itself.  For instance Storable v0.7 create files
in format v2.0 and Storable v2.15 create files in format v2.7.  The