doc/html/_sources/plugindev/locate.txt

   1 Server location interface (locate)
   2 ==================================
   3
   4 The locate interface allows modules to control how KDCs and similar
   5 services are located by clients.  For a detailed description of the
   6 ccselect interface, see the header file ``<krb5/locate_plugin.h>``.
   7
   8 .. note: The locate interface does not follow the normal conventions
   9          for MIT krb5 pluggable interfaces, because it was made public
  10          before those conventions were established.
  11
  12 A locate module exports a structure object of type
  13 krb5plugin_service_locate_ftable, with the name ``service_locator``.
  14 The structure contains a minor version and pointers to the module's
  15 methods.
  16
  17 The primary locate method is **lookup**, which accepts a service type,
  18 realm name, desired socket type, and desired address family (which
  19 will be AF_UNSPEC if no specific address family is desired).  The
  20 method should invoke the callback function once for each server
  21 address it wants to return, passing a socket type (SOCK_STREAM for TCP
  22 or SOCK_DGRAM for UDP) and socket address.  The **lookup** method
  23 should return 0 if it has authoritatively determined the server
  24 addresses for the realm, KRB5_PLUGIN_NO_HANDLE if it wants to let
  25 other location mechanisms determine the server addresses, or another
  26 code if it experienced a failure which should abort the location
  27 process.
  28
  29 A module can create and destroy per-library-context state objects by
  30 implementing the **init** and **fini** methods.  State objects have
  31 the type void \*, and should be cast to an internal type for the state
  32 object.