-/* This file contains definitions for use by the Hesiod name service and
- * applications.
+/*! \file hesiod.h
+ * WSHelper DNS/Hesiod Library
*
- * @doc
- *
- * @module hesiod.h |
- * For copying and distribution information, see the file
- * <gt> mit-copyright.h <lt>.
- *
- * Original version by Steve Dyer, IBM/Project Athena.
- *
- */
-
-/* Configuration information. */
+ * This file contains the function declaration for: \n
+ * hes_to_bind() \n
+ * hes_resolve() \n
+ * hes_error() \n
+ * hes_free() \n
+ * hes_getmailhost() \n
+ * hes_getservbyname() \n
+ * hes_getpwnam() \n
+ * hes_getpwuid() \n
+*/
#ifndef _HESIOD_
#define _HESIOD_
-#if defined(_WINDOWS) || defined(_WIN32)
+
#include <windows.h>
-#endif
-#if defined(_WINDOWS) || defined(_WIN32)
+/*! \def HESIOD_CONF
+ * name of the hesiod configuration file. We will look at the file to determine the RHS AND LHS value before using the default.
+ * Here is a sample hesiod.cfg file: \n
+ * lhs .ns \n
+ * rhs .ATHENA.MIT.EDU \n
+ */
#define HESIOD_CONF "c:\\net\\tcp\\hesiod.cfg"
-#else
-#define HESIOD_CONF "/etc/hesiod.conf" /* Configuration file. */
-#endif
-#define DEF_RHS ".Athena.MIT.EDU" /* Defaults if HESIOD_CONF */
-#define DEF_LHS ".ns" /* file is not present. */
+/*! \def DEF_RHS
+ * default RHS value is the hesiod configuration file is not present
+ */
+#define DEF_RHS ".Athena.MIT.EDU"
-/* @doc ERROR
-/* Error codes. */
-/*
+/*! \def DEF_LHS
+ * default LHS value is the hesiod configuration file is not present
+ */
+#define DEF_LHS ".ns"
-@type HES_ER_UNINIT | -1 uninitialized
-@type HES_ER_OK | 0 no error
-@type HES_ER_NOTFOUND | 1 Hesiod name not found by server
-@type HES_ER_CONFIG | 2 local problem (no config file?)
-@type HES_ER_NET | 3 network problem
+/*! \def HES_ER_UNINIT
+ * HES error code: uninitialized
+ */
+#define HES_ER_UNINIT -1
+/*! \def HES_ER_OK
+ * HES error code: no error
*/
+#define HES_ER_OK 0
-#define HES_ER_UNINIT -1 /* uninitialized */
-#define HES_ER_OK 0 /* no error */
-#define HES_ER_NOTFOUND 1 /* Hesiod name not found by server */
-#define HES_ER_CONFIG 2 /* local problem (no config file?) */
-#define HES_ER_NET 3 /* network problem */
+/*! \def HES_ER_NOTFOUND
+ * HES error code: Hesiod name not found by server
+ */
+#define HES_ER_NOTFOUND 1
+
+/*! \def HES_ER_CONFIG
+ * HES error code: local problem (no config file?)
+ */
+#define HES_ER_CONFIG 2
+
+/*! \def HES_ER_NET
+ * HES error code: network problem
+ */
+#define HES_ER_NET 3
-/* Declaration of routines */
#ifdef __cplusplus
extern "C" {
#endif
-#if defined(_WINDOWS) || defined(_WIN32)
-
+/*! \fn LPSTR WINAPI hes_to_bind(LPSTR HesiodName, LPSTR HesiodNameType)
+ * hes_to_bind function use the LHS and RHS values and
+ * binds them with the parameters so that a well formed DNS query may
+ * be performed.
+ *
+ * defined in hesiod.c
+ *
+ * \param[in] HesiodName The Hesiod name such as a username or service name
+ * \param[in] HesiodNameType The Hesiod name type such as pobox, passwd, or sloc
+ * \retval Returns NULL if there was an error. Otherwise the pointer to a string containing a valid query is returned.
+ *
+ */
LPSTR WINAPI
hes_to_bind(
LPSTR HesiodName,
LPSTR HesiodNameType
);
+
+/*! \fn LPSTR * WINAPI hes_resolve(LPSTR HesiodName, LPSTR HesiodNameType)
+ * This function calls hes_to_bind to form a valid hesiod query, then queries the dns database.
+ *
+ * defined in hesiod.c
+ *
+ * \param[in] HesiodName The Hesiod name such as a username or service name
+ * \param[in] HesiodNameType The Hesiod name type such as pobox, passwd, or sloc
+ * \retval returns a NULL terminated vector of strings (a la argv),
+ * one for each resource record containing Hesiod data, or NULL if
+ * there is any error. If there is an error call hes_error() to get
+ * further information. You will need to call hes_free to free the result
+ *
+ */
+
LPSTR * WINAPI
hes_resolve(
LPSTR HesiodName,
LPSTR HesiodNameType
);
+/*! \fn int WINAPI hes_error(void)
+ * The function hes_error may be called to determine the
+ * source of the error. It does not take an argument.
+ *
+ * defined in hesiod.c
+ *
+ * \retval return one of the HES_ER_* codes defined in hesiod.h.
+ */
+
int WINAPI
hes_error(
void
);
-#else
-char *hes_to_bind(const char *name, const char *type);
-char **hes_resolve(const char *name, const char *type);
-int hes_error(void);
-#endif /* WINDOWS */
-
-/*
- * @doc
- *
- * @struct hes_postoffice | For use in getting post-office information.
+/*! \fn void WINAPI hes_free(LPSTR* hesinfo)
+ * The function hes_free should be called to free up memeory returned by hes_resolve
*
- * @field LPSTR | po_type | The post office type, e.g. POP, IMAP
- * @field LPSTR | po_host | The post office host, e.g. PO10.MIT.EDU
- * @field LPSTR | po_name | The account name on the post office, e.g. tom
+ * defined in hesiod.c
*
+ * \param[in] hesinfo a NULL terminiated array of strings returned by hes_resolve
+ */
+void WINAPI
+hes_free(
+ LPSTR* hesinfo
+ );
+
+
+/*! \struct hes_postoffice
+ * For use in getting post-office information.
*/
-#if defined(_WINDOWS) || defined(_WIN32)
struct hes_postoffice {
+ /*! The post office type, e.g. POP, IMAP */
LPSTR po_type;
+ /*! The post office host, e.g. PO10.MIT.EDU */
LPSTR po_host;
+ /*! The account name on the post office, e.g. tom */
LPSTR po_name;
};
-#else
-struct hes_postoffice {
- char *po_type;
- char *po_host;
- char *po_name;
-};
-#endif
-/* Other routines */
-
-#if defined(_WINDOWS) || defined(_WIN32)
-struct hes_postoffice FAR * WINAPI hes_getmailhost(LPSTR user);
-struct servent FAR * WINAPI hes_getservbyname(LPSTR name,
- LPSTR proto);
-struct passwd FAR * WINAPI hes_getpwnam(LPSTR nam);
-struct passwd FAR * WINAPI hes_getpwuid(int uid);
-#else
-struct hes_postoffice *hes_getmailhost();
-struct servent *hes_getservbyname();
-struct passwd *hes_getpwnam();
-struct passwd *hes_getpwuid();
-#endif
+/*! \fn struct hes_postoffice * WINAPI hes_getmailhost(LPSTR user)
+ * This call is used to obtain a user's type of mail account and the location of that
+ * account. E.g. POP PO10.MIT.EDU or IMAP IMAP-TEST.MIT.EDU
+ *
+ * defined in hesmailh.c
+ *
+ * \param[in] user The username to be used when querying for the Hesiod Name Type POBOX.
+ * \retval NULL if there was an error or if there was no entry for the
+ * username. Otherwise a pointer to a hes_postoffice structure is
+ * returned. The caller must never attempt to modify this structure or to free
+ * any of its components. Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
+ * issuing another getmailhost call
+ */
+struct hes_postoffice * WINAPI hes_getmailhost(LPSTR user);
+
+/*! \fn struct servent * WINAPI hes_getservbyname(LPSTR name, LPSTR proto)
+ * This function will query a Hesiod server for a servent structure given
+ * a service name and protocol. This is a replacement for the Winsock
+ * getservbyname function which normally just uses a local services
+ * file. This allows a site to use a centralized database for adding new
+ * services.
+ *
+ * defined in hesservb.c
+ *
+ * \param[in] name pointer to the official name of the service, eg "POP3".
+ * \param[in] proto pointer to the protocol to use when contacting the service, e.g. "TCP"
+ * \retval NULL if there was an error or a pointer to a servent structure. The caller must
+ * never attempt to modify this structure or to free any of its components.
+ * Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
+ * issuing another hes_getservbyname call
+ *
+ */
+struct servent * WINAPI hes_getservbyname(LPSTR name,
+ LPSTR proto);
+
+/*! \fn struct passwd * WINAPI hes_getpwnam(LPSTR nam)
+ * Given a username this function will return the pwd information, eg
+ * username, uid, gid, fullname, office location, phone number, home
+ * directory, and default shell
+ *
+ * defined in hespwnam.c
+ *
+ * \param nam a pointer to the username
+ * \retval NULL if there was an error or a pointer to the passwd structure. The caller must
+ * never attempt to modify this structure or to free any of its components.
+ * Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
+ * issuing another hes_getpwnam call
+ *
+ */
+struct passwd * WINAPI hes_getpwnam(LPSTR nam);
+
+/*! struct passwd * WINAPI hes_getpwuid(int uid)
+ * Given a UID this function will return the pwd information, eg username, uid,
+ * gid, fullname, office location, phone number, home directory, and default shell
+ *
+ * defined in hespwnam.c
+ *
+ * \param uid The user ID
+ * \retval NULL if there was an error or a pointer to the passwd structure. The caller must
+ * never attempt to modify this structure or to free any of its components.
+ * Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
+ * issuing another hes_getpwuid call
+ */
+struct passwd * WINAPI hes_getpwuid(int uid);
#ifdef __cplusplus
}
git://git.openafs.org / openafs.git / blobdiff