src/WINNT/kfw/inc/wshelper/hesiod.h

   1 /*!     \file hesiod.h
   2  *      WSHelper DNS/Hesiod Library
   3  *
   4  *      This file contains the function declaration for: \n
   5  *      hes_to_bind()   \n
   6  *      hes_resolve()   \n
   7  *      hes_error()             \n
   8  *      hes_free()              \n
   9  *      hes_getmailhost()       \n
  10  *      hes_getservbyname()     \n
  11  *      hes_getpwnam()  \n
  12  *      hes_getpwuid()  \n
  13 */
  14
  15 #ifndef _HESIOD_
  16 #define _HESIOD_
  17
  18
  19 #include <windows.h>
  20
  21 /*! \def HESIOD_CONF
  22  *      name of the hesiod configuration file. We will look at the file to determine the RHS AND LHS value before using the default.
  23  *  Here is a sample hesiod.cfg file: \n
  24  *      lhs .ns \n
  25  *      rhs .ATHENA.MIT.EDU \n
  26  */
  27 #define HESIOD_CONF     "c:\\net\\tcp\\hesiod.cfg"
  28
  29 /*! \def DEF_RHS
  30  *      default RHS value is the hesiod configuration file is not present
  31  */
  32 #define DEF_RHS         ".Athena.MIT.EDU"
  33
  34 /*! \def DEF_LHS
  35  *      default LHS value is the hesiod configuration file is not present
  36  */
  37 #define DEF_LHS         ".ns"
  38
  39 /*! \def HES_ER_UNINIT
  40  *      HES error code: uninitialized
  41  */
  42 #define HES_ER_UNINIT   -1
  43
  44 /*! \def HES_ER_OK
  45  *      HES error code: no error
  46  */
  47 #define HES_ER_OK       0
  48
  49 /*! \def HES_ER_NOTFOUND
  50  *      HES error code: Hesiod name not found by server
  51  */
  52 #define HES_ER_NOTFOUND 1
  53
  54 /*! \def HES_ER_CONFIG
  55  *      HES error code: local problem (no config file?)
  56  */
  57 #define HES_ER_CONFIG   2
  58
  59 /*! \def HES_ER_NET
  60  *      HES error code: network problem
  61  */
  62 #define HES_ER_NET      3
  63
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /*!     \fn LPSTR WINAPI hes_to_bind(LPSTR HesiodName, LPSTR HesiodNameType)
  70  *      hes_to_bind function use the LHS and RHS values and
  71  *      binds them with the parameters so that a well formed DNS query may
  72  *      be performed.
  73  *
  74  *      defined in hesiod.c
  75  *
  76  *      \param[in]      HesiodName              The Hesiod name such as a username or service name
  77  *      \param[in]      HesiodNameType  The Hesiod name type such as pobox, passwd, or sloc
  78  *      \retval         Returns NULL if there was an error. Otherwise the pointer to a string containing a valid query is returned.
  79  *
  80  */
  81 LPSTR WINAPI
  82 hes_to_bind(
  83     LPSTR HesiodName,
  84     LPSTR HesiodNameType
  85     );
  86
  87
  88 /*!     \fn LPSTR * WINAPI hes_resolve(LPSTR HesiodName, LPSTR HesiodNameType)
  89  *      This function calls hes_to_bind to form a valid hesiod query, then queries the dns database.
  90  *
  91  *      defined in hesiod.c
  92  *
  93  *      \param[in]      HesiodName              The Hesiod name such as a username or service name
  94  *      \param[in]      HesiodNameType  The Hesiod name type such as pobox, passwd, or sloc
  95  *      \retval         returns a NULL terminated vector of strings (a la argv),
  96  *                              one for each resource record containing Hesiod data, or NULL if
  97  *                              there is any error. If there is an error call hes_error() to get
  98  *                              further information. You will need to call hes_free to free the result
  99  *
 100  */
 101
 102 LPSTR * WINAPI
 103 hes_resolve(
 104     LPSTR HesiodName,
 105     LPSTR HesiodNameType
 106     );
 107
 108 /*! \fn  int WINAPI hes_error(void)
 109  *      The  function  hes_error may be called to determine the
 110  *      source of the error.  It does not take an argument.
 111  *
 112  *      defined in hesiod.c
 113  *
 114  *      \retval         return one of the HES_ER_* codes defined in hesiod.h.
 115  */
 116
 117 int WINAPI
 118 hes_error(
 119     void
 120     );
 121
 122
 123 /*! \fn void WINAPI hes_free(LPSTR* hesinfo)
 124  * The function hes_free should be called to free up memeory returned by hes_resolve
 125  *
 126  * defined in hesiod.c
 127  *
 128  * \param[in]   hesinfo         a NULL terminiated array of strings returned by hes_resolve
 129  */
 130 void WINAPI
 131 hes_free(
 132     LPSTR* hesinfo
 133     );
 134
 135
 136 /*! \struct hes_postoffice
 137  * For use in getting post-office information.
 138  */
 139 struct hes_postoffice {
 140         /*! The post office type, e.g. POP, IMAP */
 141     LPSTR   po_type;
 142         /*! The post office host, e.g. PO10.MIT.EDU */
 143     LPSTR   po_host;
 144         /*! The account name on the post office, e.g. tom */
 145     LPSTR   po_name;
 146 };
 147
 148 /*! \fn struct hes_postoffice  * WINAPI hes_getmailhost(LPSTR user)
 149  * This call is used to obtain a user's type of mail account and the location of that
 150  *      account. E.g. POP PO10.MIT.EDU or IMAP IMAP-TEST.MIT.EDU
 151  *
 152  *      defined in hesmailh.c
 153  *
 154  *      \param[in]      user    The username to be used when querying for the Hesiod Name Type POBOX.
 155  *      \retval                         NULL if there was an error or if there was no entry for the
 156  *                                              username. Otherwise a pointer to a hes_postoffice structure is
 157  *                                              returned. The caller must never attempt to modify this structure or to free
 158  *                                              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
 159  *                                              issuing another getmailhost call
 160  */
 161 struct hes_postoffice  * WINAPI hes_getmailhost(LPSTR user);
 162
 163 /*!     \fn struct servent  * WINAPI hes_getservbyname(LPSTR name, LPSTR proto)
 164  *      This function will query a Hesiod server for a servent structure given
 165  *      a service name and protocol. This is a replacement for the Winsock
 166  *      getservbyname function which normally just uses a local services
 167  *      file. This allows a site to use a centralized database for adding new
 168  *      services.
 169  *
 170  *      defined in hesservb.c
 171  *
 172  *      \param[in]      name    pointer to the official name of the service, eg "POP3".
 173  *      \param[in]      proto   pointer to the protocol to use when contacting the service, e.g. "TCP"
 174  *      \retval                         NULL if there was an error or a pointer to a servent structure. The caller must
 175  *                                              never attempt to modify this structure or to free any of its components.
 176  *                                              Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
 177  *                                              issuing another hes_getservbyname call
 178  *
 179  */
 180 struct servent  * WINAPI hes_getservbyname(LPSTR name,
 181                                               LPSTR proto);
 182
 183 /*! \fn struct passwd  * WINAPI hes_getpwnam(LPSTR nam)
 184  *      Given a username this function will return the pwd information, eg
 185  *      username, uid, gid, fullname, office location, phone number, home
 186  *      directory, and default shell
 187  *
 188  *      defined in hespwnam.c
 189  *
 190  *      \param  nam                     a pointer to the username
 191  *      \retval                         NULL if there was an error or a pointer to the passwd structure. The caller must
 192  *                                              never attempt to modify this structure or to free any of its components.
 193  *                                              Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
 194  *                                              issuing another hes_getpwnam call
 195  *
 196  */
 197 struct passwd  * WINAPI hes_getpwnam(LPSTR nam);
 198
 199 /*!  struct passwd  * WINAPI hes_getpwuid(int uid)
 200  *      Given a UID this function will return the pwd information, eg username, uid,
 201  *      gid, fullname, office location, phone number, home directory, and default shell
 202  *
 203  *      defined in hespwnam.c
 204  *
 205  *      \param  uid                     The user ID
 206  *      \retval                         NULL if there was an error or a pointer to the passwd structure. The caller must
 207  *                                              never attempt to modify this structure or to free any of its components.
 208  *                                              Furthermore, only one copy of this structure is allocated per call per thread, so the application should copy any information it needs before
 209  *                                              issuing another hes_getpwuid call
 210  */
 211 struct passwd  * WINAPI hes_getpwuid(int uid);
 212
 213 #ifdef __cplusplus
 214 }
 215 #endif
 216
 217 #endif /* _HESIOD_ */