X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_identity_service.h;h=e07951de7dbbd1b390f75515383c60fb978b751a;hb=bb5fe91d23b0938baa3c4f0e92a83df659df216a;hp=23dee600f3198a0caa7b0c0b5ffb43bef5bf15b6;hpb=303ab4dafbc680b1b362f95df5b12dae831b1593;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h
index 23dee600f..e07951de7 100644
--- a/src/include/gnunet_identity_service.h
+++ b/src/include/gnunet_identity_service.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2013 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2013 GNUnet e.V.
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -14,23 +14,30 @@
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+     Boston, MA 02110-1301, USA.
 */
 
-/** 
- * @file include/gnunet_identity_service.h
- * @brief Identity service; implements identity management for GNUnet
+/**
  * @author Christian Grothoff
  *
- * Identities in GNUnet are ECDSA keys.  You assume an identity by
- * using (signing with) a particular private key.  As GNUnet users are
- * expected to have many egos, we need an identity service to
- * allow users to manage their egos.  The identity service
- * manages the egos (private keys) of the local user; it does
- * NOT manage identities of other users (public keys).  For giving
- * names to other users and manage their public keys securely, we
- * use GADS/GNS.
+ * @file
+ * Identity service; implements identity management for GNUnet
+ *
+ * @defgroup identity  Identity service
+ * Identity management.
+ *
+ * Egos in GNUnet are ECDSA keys.  You assume an ego by using (signing
+ * with) a particular private key.  As GNUnet users are expected to
+ * have many egos, we need an identity service to allow users to
+ * manage their egos.  The identity service manages the egos (private
+ * keys) of the local user; it does NOT manage egos of other users
+ * (public keys).  For giving names to other users and manage their
+ * public keys securely, we use GNS.
+ *
+ * @see [Documentation](https://gnunet.org/identity-subsystem)
+ *
+ * @{
  */
 #ifndef GNUNET_IDENTITY_SERVICE_H
 #define GNUNET_IDENTITY_SERVICE_H
@@ -46,22 +53,22 @@ extern "C"
 #include "gnunet_util_lib.h"
 
 
-/** 
+/**
  * Version number of GNUnet Identity API.
  */
 #define GNUNET_IDENTITY_VERSION 0x00000000
 
-/** 
+/**
  * Handle to access the identity service.
  */
 struct GNUNET_IDENTITY_Handle;
 
-/** 
+/**
  * Handle for a ego.
  */
 struct GNUNET_IDENTITY_Ego;
 
-/** 
+/**
  * Handle for an operation with the identity service.
  */
 struct GNUNET_IDENTITY_Operation;
@@ -73,14 +80,14 @@ struct GNUNET_IDENTITY_Operation;
  * @param ego the ego
  * @return associated ECC key, valid as long as the ego is valid
  */
-const struct GNUNET_CRYPTO_EccPrivateKey *
+const struct GNUNET_CRYPTO_EcdsaPrivateKey *
 GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego);
 
 
 /**
  * Obtain the ego representing 'anonymous' users.
  *
- * @returns handle for the anonymous user, must not be freed
+ * @return handle for the anonymous user, must not be freed
  */
 const struct GNUNET_IDENTITY_Ego *
 GNUNET_IDENTITY_ego_get_anonymous (void);
@@ -94,56 +101,57 @@ GNUNET_IDENTITY_ego_get_anonymous (void);
  */
 void
 GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego,
-				    struct GNUNET_CRYPTO_EccPublicKey *pk);
+				    struct GNUNET_CRYPTO_EcdsaPublicKey *pk);
 
 
-/** 
+/**
  * Method called to inform about the egos of
- * this peer. 
+ * this peer.
  *
- * When used with 'GNUNET_IDENTITY_connect', this function is
+ * When used with #GNUNET_IDENTITY_connect, this function is
  * initially called for all egos and then again whenever a
  * ego's name changes or if it is deleted.  At the end of
  * the initial pass over all egos, the function is once called
- * with 'NULL' for 'ego'. That does NOT mean that the callback won't
+ * with 'NULL' for @a ego. That does NOT mean that the callback won't
  * be invoked in the future or that there was an error.
  *
- * When used with 'GNUNET_IDENTITY_create' or 'GNUNET_IDENTITY_get',
+ * When used with #GNUNET_IDENTITY_create or #GNUNET_IDENTITY_get,
  * this function is only called ONCE, and 'NULL' being passed in
- * 'ego' does indicate an error (i.e. name is taken or no default
- * value is known).  If 'ego' is non-NULL and if '*ctx'
+ * @a ego does indicate an error (i.e. name is taken or no default
+ * value is known).  If @a ego is non-NULL and if '*ctx'
  * is set in those callbacks, the value WILL be passed to a subsequent
- * call to the identity callback of 'GNUNET_IDENTITY_connect' (if 
+ * call to the identity callback of #GNUNET_IDENTITY_connect (if
  * that one was not NULL).
  *
  * When an identity is renamed, this function is called with the
- * (known) ego but the NEW name.  
+ * (known) @a ego but the NEW @a name.
  *
  * When an identity is deleted, this function is called with the
- * (known) ego and "NULL" for the 'name'.  In this case,
- * the 'ego' is henceforth invalid (and the 'ctx' should also be
+ * (known) ego and "NULL" for the @a name.  In this case,
+ * the @a ego is henceforth invalid (and the @a ctx should also be
  * cleaned up).
  *
  * @param cls closure
  * @param ego ego handle
- * @param ego_ctx context for application to store data for this ego
+ * @param ctx context for application to store data for this ego
  *                 (during the lifetime of this process, initially NULL)
  * @param name name assigned by the user for this ego,
  *                   NULL if the user just deleted the ego and it
  *                   must thus no longer be used
  */
-typedef void (*GNUNET_IDENTITY_Callback)(void *cls,
-					 struct GNUNET_IDENTITY_Ego *ego,
-					 void **ctx,
-					 const char *name);
+typedef void
+(*GNUNET_IDENTITY_Callback)(void *cls,
+                            struct GNUNET_IDENTITY_Ego *ego,
+                            void **ctx,
+                            const char *name);
 
 
-/** 
+/**
  * Connect to the identity service.
  *
  * @param cfg Configuration to contact the identity service.
  * @param cb function to call on all identity events, can be NULL
- * @param cb_cls closure for 'cb'
+ * @param cb_cls closure for @a cb
  * @return handle to communicate with identity service
  */
 struct GNUNET_IDENTITY_Handle *
@@ -153,13 +161,13 @@ GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 
 
 /**
- * Obtain the identity that is currently preferred/default
+ * Obtain the ego that is currently preferred/default
  * for a service.
  *
  * @param id identity service to query
  * @param service_name for which service is an identity wanted
  * @param cb function to call with the result (will only be called once)
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_Operation *
@@ -176,18 +184,19 @@ GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id,
  * @param cls closure
  * @param emsg NULL on success, otherwise an error message
  */
-typedef void (*GNUNET_IDENTITY_Continuation)(void *cls,
-					     const char *emsg);
+typedef void
+(*GNUNET_IDENTITY_Continuation)(void *cls,
+                                const char *emsg);
 
 
 /**
- * Set the preferred/default identity for a service.
+ * Set the preferred/default ego for a service.
  *
  * @param id identity service to inform
  * @param service_name for which service is an identity set
  * @param ego new default identity to be set for this service
  * @param cont function to call once the operation finished
- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_Operation *
@@ -202,18 +211,18 @@ GNUNET_IDENTITY_set (struct GNUNET_IDENTITY_Handle *id,
  * Disconnect from identity service.
  *
  * @param h identity service to disconnect
- */ 
+ */
 void
 GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h);
 
 
-/** 
- * Create a new identity with the given name.
+/**
+ * Create a new ego with the given name.
  *
  * @param id identity service to use
  * @param name desired name
  * @param cont function to call with the result (will only be called once)
- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_Operation *
@@ -223,14 +232,14 @@ GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
 			void *cont_cls);
 
 
-/** 
- * Renames an existing identity.
+/**
+ * Renames an existing ego.
  *
  * @param id identity service to use
  * @param old_name old name
  * @param new_name desired new name
  * @param cb function to call with the result (will only be called once)
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_Operation *
@@ -241,13 +250,13 @@ GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id,
 			void *cb_cls);
 
 
-/** 
- * Delete an existing identity.
+/**
+ * Delete an existing ego.
  *
  * @param id identity service to use
  * @param name name of the identity to delete
  * @param cb function to call with the result (will only be called once)
- * @param cb_cls closure for cb
+ * @param cb_cls closure for @a cb
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_Operation *
@@ -269,6 +278,49 @@ void
 GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
 
 
+/* ************* convenience API to lookup an ego ***************** */
+
+/**
+ * Function called with the result.
+ *
+ * @param cls closure
+ * @param ego NULL on error / ego not found
+ */
+typedef void
+(*GNUNET_IDENTITY_EgoCallback)(void *cls,
+                               const struct GNUNET_IDENTITY_Ego *ego);
+
+/**
+ * Handle for ego lookup.
+ */
+struct GNUNET_IDENTITY_EgoLookup;
+
+
+/**
+ * Lookup an ego by name.
+ *
+ * @param cfg configuration to use
+ * @param name name to look up
+ * @param cb callback to invoke with the result
+ * @param cb_cls closure for @a cb
+ * @return NULL on error
+ */
+struct GNUNET_IDENTITY_EgoLookup *
+GNUNET_IDENTITY_ego_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
+			    const char *name,
+			    GNUNET_IDENTITY_EgoCallback cb,
+			    void *cb_cls);
+
+
+/**
+ * Abort ego lookup attempt.
+ *
+ * @param el handle for lookup to abort
+ */
+void
+GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el);
+
+
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
@@ -278,4 +330,7 @@ GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
 
 /* ifndef GNUNET_IDENTITY_SERVICE_H */
 #endif
+
+/** @} */ /* end of group identity */
+
 /* end of gnunet_identity_service.h */