From 52af81697727b861687914ca983ea73e8dc65ad0 Mon Sep 17 00:00:00 2001
From: Griatch <griatch@gmail.com>
Date: Sun, 28 Oct 2012 14:07:18 +0100
Subject: [PATCH] Added hooks at_access_success and at_access_failure to allow
 for custom messaging for certain lock errors. Resolves Issue 311.

---
 game/gamesrc/objects/examples/object.py |  3 ++
 src/objects/objects.py                  | 37 +++++++++++++++++++++----
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/game/gamesrc/objects/examples/object.py b/game/gamesrc/objects/examples/object.py
index d2129dd098..dab653d155 100644
--- a/game/gamesrc/objects/examples/object.py
+++ b/game/gamesrc/objects/examples/object.py
@@ -98,6 +98,9 @@ class ExampleObject(Object):
      at_server_reload()   - called before server is reloaded
      at_server_shutdown() - called just before server is fully shut down
 
+     at_access_success(accessing_obj, access_type) - called if an lock access check succeeded on this object
+     at_access_failure(accessing_obj, access_type) - called if an lock access check failed on this object
+
      at_before_move(destination)             - called just before moving object to the destination. If returns False, move is cancelled.
      announce_move_from(destination)         - called in old location, just before move, if obj.move_to() has quiet=False
      announce_move_to(source_location)       - called in new location, just after move, if obj.move_to() has quiet=False
diff --git a/src/objects/objects.py b/src/objects/objects.py
index 587f5c3925..de9caea19d 100644
--- a/src/objects/objects.py
+++ b/src/objects/objects.py
@@ -343,8 +343,17 @@ class Object(TypeClass):
           accessing_obj (Object)- object trying to access this one
           access_type (string) - type of access sought
           default (bool) - what to return if no lock of access_type was found
+
+        This function will call at_access_success or at_access_failure depending on the
+        outcome of the access check.
+
         """
-        return self.dbobj.access(accessing_obj, access_type=access_type, default=default)
+        if self.dbobj.access(accessing_obj, access_type=access_type, default=default):
+            self.at_access_success(accessing_obj, access_type)
+            return True
+        else:
+            self.at_access_failure(accessing_obj, access_type)
+            return False
 
     def check_permstring(self, permstring):
         """
@@ -486,6 +495,23 @@ class Object(TypeClass):
         """
         pass
 
+    def at_access_success(self, accessing_obj, access_type):
+        """
+        This hook is called whenever accessing_obj succeed a lock check of type access_type
+        on this object, for whatever reason. The return value of this hook is not used,
+        the lock will still pass regardless of what this hook does (use lockstring/funcs to tweak
+        the lock result).
+        """
+        pass
+
+    def at_access_failure(self, accessing_obj, access_type):
+        """
+        This hook is called whenever accessing_obj fails a lock check of type access_type
+        on this object, for whatever reason. The return value of this hook is not used, the
+        lock will still fail regardless of what this hook does (use lockstring/funcs to tweak the
+        lock result).
+        """
+        pass
 
     # hooks called when moving the object
 
@@ -571,7 +597,6 @@ class Object(TypeClass):
         """
         pass
 
-
     def at_before_traverse(self, traversing_object):
         """
         Called just before an object uses this object to
@@ -621,9 +646,11 @@ class Object(TypeClass):
         msg is passed on to the user sesssion. If this
         method returns False, the msg will not be
         passed on.
-
-        msg = the message received
-        from_obj = the one sending the message
+        Input:
+            msg = the message received
+            from_obj = the one sending the message
+        Output:
+            boolean True/False
         """
         return True