initial import of finished admin api

--HG--
extra : convert_revision : svn%3A39bc706e-5318-0410-9160-8a85361fbb7c/trunk%40410

public/IAdminSystem.h

@@ -43,6 +43,8 @@
  *  3] An override table - insertion and retrieval only.
  *   Individual groups can be invalidated entirely.  It should be considered an expensive
  *  operation, since each admin needs to be patched up to not reference the group.
+ *
+ *   For more information, see the SourceMod Development wiki.
  */
 
 namespace SourceMod
@@ -98,11 +100,25 @@ namespace SourceMod
 		Immunity_Global,		/**< Immune from everyone (except root admins) */
 	};
 
+	/**
+	 * @brief Defines user access modes.
+	 */
+	enum AccessMode
+	{
+		Access_Real,		/**< Access the user has inherently */
+		Access_Effective,	/**< Access the user has from their groups */
+	};
+
 	/**
 	 * @brief Represents an index to one group.
 	 */
 	typedef int		GroupId;
 
+	/**
+	 * @brief Represents an index to one user entry.
+	 */
+	typedef int		AdminId;
+
 	#define ADMIN_CACHE_OVERRIDES	(1<<0)
 	#define ADMIN_CACHE_ADMINS		(1<<1)
 	#define ADMIN_CACHE_GROUPS		((1<<2)|ADMIN_CACHE_ADMINS)
@@ -112,6 +128,11 @@ namespace SourceMod
 	 */
 	#define INVALID_GROUP_ID	-1
 
+	/**
+	 * @brief Represents an invalid/nonexistant user or an erroneous operation.
+	 */
+	#define INVALID_ADMIN_ID	-1
+
 	/**
 	 * @brief Provides callbacks for admin cache operations.
 	 */
@@ -315,6 +336,140 @@ namespace SourceMod
 		 * @param pListener		Pointer to an IAdminListener to remove.
 		 */
 		virtual void RemoveAdminListener(IAdminListener *pListener) =0;
+
+		/**
+		 * @brief Registers an authentication identity type.
+		 * Note: Default types are "steam," "name," and "ip."
+		 *
+		 * @param name			String containing the type name.
+		 */
+		virtual void RegisterAuthIdentType(const char *name) =0;
+
+		/**
+		 * @brief Creates a new user entry.
+		 *
+		 * @param name		Name for this entry (does not have to be unique).
+		 *					Specify NULL for an anonymous admin.
+		 * @return			A new AdminId index.
+		 */
+		virtual AdminId CreateAdmin(const char *name) =0;
+
+		/**
+		 * @brief Gets an admin's user name.
+		 *
+		 * @param id		AdminId index for this admin.
+		 * @return			A string containing the admin's name, or NULL
+		 *					if the admin was created anonymously.
+		 */
+		virtual const char *GetAdminName(AdminId id) =0;
+
+		/**
+		 * @brief Binds a user entry to a particular auth method.
+		 * This bind must be unique.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param auth		Auth method to use.
+		 * @param ident		Identity string to bind to.
+		 * @return			True on success, false if auth method was not found,
+		 *					id was invalid, or ident was already taken.
+		 */
+		virtual bool BindAdminIdentity(AdminId id, const char *auth, const char *ident) =0;
+
+		/**
+		 * @brief Sets whether or not a flag is enabled on an admin.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param flag		Admin flag to use.
+		 * @param enabled	True to enable, false to disable.
+		 */
+		virtual void SetAdminFlag(AdminId id, AdminFlag flag, bool enabled) =0;
+
+		/**
+		 * @brief Returns whether or not a flag is enabled on an admin.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param flag		Admin flag to use.
+		 * @param mode		Access mode to check.
+		 * @return			True if enabled, false otherwise.
+		 */
+		virtual bool GetAdminFlag(AdminId id, AdminFlag flag, AccessMode mode) =0;
+
+		/**
+		 * @brief Returns a bitarray of flags enabled on an admin.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param flag		Array to store flag bits in.
+		 * @param total		Maximum size of the flag array.
+		 * @param mode		Access mode to use.
+		 * @return			Number of flags written to the array.
+		 */
+		virtual unsigned int GetAdminFlags(AdminId id, 
+										   bool flags[], 
+										   unsigned int total, 
+										   AccessMode mode) =0;
+
+		/**
+		 * @brief Adds a group to an admin's inherited group list.  
+		 * Any flags the group has will be added to the admin's effective flags.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param gid		GroupId index of the group.
+		 * @return			True on success, false on invalid input or duplicate membership.
+		 */
+		virtual bool AdminInheritGroup(AdminId id, GroupId gid) =0;
+
+		/**
+		 * @brief Returns the number of groups this admin is a member of.
+		 * 
+		 * @param id		AdminId index of the admin.
+		 * @return			Number of groups this admin is a member of.
+		 */
+		virtual unsigned int GetAdminGroupCount(AdminId id) =0;
+
+		/**
+		 * @brief Returns group information from an admin.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param index		Group number to retrieve, from 0 to N-1, where N
+		 *					is the value of GetAdminGroupCount(id).
+		 * @param name		Optional pointer to store the group's name.
+		 * @return			A GroupId index and a name pointer, or
+		 *					INVALID_GROUP_ID and NULL if an error occurred.
+		 */
+		virtual GroupId GetAdminGroup(AdminId id, unsigned int index, const char **name) =0;
+		
+		/**
+		 * @brief Sets a password on an admin.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @param passwd	String containing the password.
+		 */
+		virtual void SetAdminPassword(AdminId id, const char *password) =0;
+
+		/**
+		 * @brief Gets an admin's password.
+		 *
+		 * @param id		AdminId index of the admin.
+		 * @return			Password of the admin, or NULL if none.
+		 */
+		virtual const char *GetAdminPassword(AdminId id) =0;
+		
+		/**
+		 * @brief Attempts to find an admin by an auth method and an identity.
+		 *
+		 * @param auth		Auth method to try.
+		 * @param identity	Identity string to look up.
+		 * @return			An AdminId index if found, INVALID_ADMIN_ID otherwise.
+		 */
+		virtual AdminId FindAdminByIdentity(const char *auth, const char *identity) =0;
+
+		/**
+		 * @brief Invalidates an admin from the cache so its resources can be re-used.
+		 *
+		 * @param id		AdminId index to invalidate.
+		 * @return			True on success, false otherwise.
+		 */
+		virtual bool InvalidateAdmin(AdminId id) =0;
 	};
 };