1 files changed, 196 insertions, 1 deletions
diff --git a/perl/Wallet/Object.pm b/perl/Wallet/Object.pm
index 0cc7d69..602b426 100644
--- a/perl/Wallet/Object.pm
+++ b/perl/Wallet/Object.pm
@@ -79,9 +79,15 @@ sub create {
 }
 
 ##############################################################################
-# History functions
+# Utility functions
 ##############################################################################
 
+# Returns the current error message of the object, if any.
+sub error {
+    my ($self) = @_;
+    return $self->{error};
+}
+
 # Record a global object action for this object.  Takes the action (which must
 # be one of get or store), and the trace information: user, host, and time.
 # Returns true on success and false on failure, setting error appropriately.
@@ -161,6 +167,7 @@ sub log_set {
 # Returns undef on failure and the new value on success.
 sub _set_internal {
     my ($self, $attr, $value, $user, $host, $time) = @_;
+    $time ||= time;
     my $name = $self->{name};
     my $type = $self->{type};
     eval {
@@ -307,6 +314,7 @@ sub show {
 # is stored about this object.
 sub destroy {
     my ($self, $user, $host, $time) = @_;
+    $time ||= time;
     my $name = $self->{name};
     my $type = $self->{type};
     eval {
@@ -327,3 +335,190 @@ sub destroy {
     }
     return 1;
 }
+
+##############################################################################
+# Documentation
+##############################################################################
+
+=head1 NAME
+
+Wallet::Object - Generic parent class for wallet objects
+
+=head1 SYNOPSIS
+
+    package Wallet::Object::Simple;
+    @ISA = qw(Wallet::Object);
+    sub get {
+        my ($self, $user, $host, $time) = @_;
+        $self->log_action ('get', $user, $host, $time) or return undef;
+        return "Some secure data";
+    }
+
+=head1 DESCRIPTION
+
+Wallet::Object is the generic parent class for wallet objects (data types
+that can be stored in the wallet system).  It provides defualt functions and
+behavior, including handling generic object settings.  All handlers for
+objects stored in the wallet should inherit from it.  It is not used
+directly.
+
+=head1 PUBLIC CLASS METHODS
+
+The following methods are called by the rest of the wallet system and should
+be implemented by all objects stored in the wallet.  They should be called
+with the desired wallet object class as the first argument (generally using
+the Wallet::Object::Type->new syntax).
+
+=over 4
+
+=item new(NAME, TYPE, DBH)
+
+Creates a new object with the given object name and type, based on data
+already in the database.  This method will only succeed if an object of the
+given NAME and TYPE is already present in the wallet database.  If no such
+object exits, returns undef.  Otherwise, returns an object blessed into the
+class used for the new() call (so subclasses can leave this method alone and
+not override it).
+
+Takes a database handle, which is stored in the object and used for any
+further operations.  This database handle is taken over by the wallet system
+and its settings (such as RaiseError and AutoCommit) will be modified by the
+object for its own needs.
+
+=item create(NAME, TYPE, DBH, PRINCIPAL, HOSTNAME [, DATETIME])
+
+Similar to new() but instead creates a new entry in the database.  This
+method will fail (returning undef) if an entry for that name and type
+already exists in the database or if creating the database record fails.
+Otherwise, a new database entry will be created with that name and type, no
+owner, no ACLs, no expiration, no flags, and with created by, from, and on
+set to the PRINCIPAL, HOSTNAME, and DATETIME parameters.  If DATETIME isn't
+given, the current time is used.  The database handle is treated as with
+new().
+
+=back
+
+=head1 PUBLIC INSTANCE METHODS
+
+The following methods may be called on instantiated wallet objects.
+Normally, the only methods that a subclass will need to override are get(),
+store(), show(), and destroy().
+
+=over 4
+
+=item acl(TYPE [, ACL, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves a given object ACL as a numeric ACL ID.  TYPE must be one
+of C<get>, C<store>, C<show>, C<destroy>, or C<flags>, corresponding to the
+ACLs kept on an object.  If no other arguments are given, returns the
+current ACL setting as an ACL ID or undef if that ACL isn't set.  If other
+arguments are given, change that ACL to ACL.  The other arguments are used
+for logging and history and should indicate the user and host from which the
+change is made and the time of the change.
+
+=item destroy(PRINCIPAL, HOSTNAME [, DATETIME])
+
+Destroys the object by removing all record of it from the database.  The
+Wallet::Object implementation handles the generic database work, but any
+subclass should override this method to do any deletion of files or entries
+in external databases and any other database entries and then call the
+parent method to handle the generic database cleanup.  Returns true on
+success and false on failure.  The arguments are used for logging and
+history and should indicate the user and host from which the change is made
+and the time of the change.
+
+=item error()
+
+Returns the error message from the last failing operation or undef if no
+operations have failed.  Callers should call this function to get the error
+message after an undef return from any other instance method.
+
+=item expires([EXPIRES, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves the expiration date of an object.  If no arguments are
+given, returns the current expiration or undef if no expiration is set.  If
+arguments are given, change the expiration to EXPIRES, which should be in
+seconds since epoch.  The other arguments are used for logging and history
+and should indicate the user and host from which the change is made and the
+time of the change.
+
+=item get(PRINCIPAL, HOSTNAME [, DATETIME])
+
+An object implementation must override this method with one that returns
+either the data of the object or undef on some error, using the provided
+arguments to update history information.  The Wallet::Object implementation
+just throws an exception.
+
+=item owner([OWNER, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves the owner of an object as a numeric ACL ID.  If no
+arguments are given, returns the current owner ACL ID or undef if none is
+set.  If arguments are given, change the owner to OWNER.  The other
+arguments are used for logging and history and should indicate the user and
+host from which the change is made and the time of the change.
+
+=item show()
+
+Returns a formatted text description of the object suitable for human
+display, or undef on error.  The default implementation shows all of the
+base metadata about the object, formatted as key: value pairs with the keys
+aligned in the first 15 characters followed by a space, a colon, and the
+value.  Object implementations with additional data to display can rely on
+that format to add additional settings into the formatted output or at the
+end with a matching format.
+
+=item store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])
+
+Store user-supplied data into the given object.  This may not be supported
+by all backends (for instance, backends that automatically generate the data
+will not support this).  The default implementation rejects all store()
+calls with an error message saying that the object is immutable.
+
+=back
+
+=head1 UTILITY METHODS
+
+The following instance methods should not be called externally but are
+provided for subclasses to call to implement some generic actions.
+
+=over 4
+
+=item log_action (ACTION, PRINCIPAL, HOSTNAME, DATETIME)
+
+Updates the history tables and trace information appropriately for ACTION,
+which should be either C<get> or C<store>.  No other changes are made to the
+database, just updates of the history table and trace fields with the
+provided data about who performed the action and when.
+
+This function commits its transaction when complete and therefore should not
+be called inside another transaction.  Normally it's called as a separate
+transaction after the data is successfully stored or retrieved.
+
+=item log_set (FIELD, OLD, NEW, PRINCIPAL, HOSTNAME, DATETIME)
+
+Updates the history tables for the change in a setting value for an object.
+FIELD should be one of C<owner>, C<acl_get>, C<acl_store>, C<acl_show>,
+C<acl_destroy>, C<acl_flags>, C<expires>, C<flags>, or a value starting with
+C<type_data> followed by a space and a type-specific field name.  The last
+form is the most common form used by a subclass.  OLD is the previous value
+of the field or undef if the field was unset, and NEW is the new value of
+the field or undef if the field should be unset.
+
+This function does not commit and does not catch database exceptions.  It
+should normally be called as part of a larger transaction that implements
+the change in the setting.
+
+=back
+
+=head1 SEE ALSO
+
+walletd(8)
+
+This module is part of the wallet system.  The current version is available
+from L<http://www.eyrie.org/~eagle/software/wallet/>.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
+
+=cut