src/include/net-server.h

   1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* include/net-server.h */
   3 /*
   4  * Copyright (C) 2010 by the Massachusetts Institute of Technology.
   5  * All rights reserved.
   6  *
   7  * Export of this software from the United States of America may
   8  *   require a specific license from the United States Government.
   9  *   It is the responsibility of any person or organization contemplating
  10  *   export to obtain such a license before exporting.
  11  *
  12  * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
  13  * distribute this software and its documentation for any purpose and
  14  * without fee is hereby granted, provided that the above copyright
  15  * notice appear in all copies and that both that copyright notice and
  16  * this permission notice appear in supporting documentation, and that
  17  * the name of M.I.T. not be used in advertising or publicity pertaining
  18  * to distribution of the software without specific, written prior
  19  * permission.  Furthermore if you modify this software you must label
  20  * your software as modified software and not distribute it in such a
  21  * fashion that it might be confused with the original M.I.T. software.
  22  * M.I.T. makes no representations about the suitability of
  23  * this software for any purpose.  It is provided "as is" without express
  24  * or implied warranty.
  25  */
  26
  27 /* Declarations for "API" of network listener/dispatcher in libapputils. */
  28
  29 #ifndef NET_SERVER_H
  30 #define NET_SERVER_H
  31
  32 #include <verto.h>
  33
  34 /* The delimeter characters supported by the addresses string. */
  35 #define ADDRESSES_DELIM ",; "
  36
  37 typedef struct _krb5_fulladdr {
  38     krb5_address *      address;
  39     krb5_ui_4           port;
  40 } krb5_fulladdr;
  41
  42 /* exported from network.c */
  43 void init_addr(krb5_fulladdr *, struct sockaddr *);
  44
  45 /* exported from net-server.c */
  46 verto_ctx *loop_init(verto_ev_type types);
  47
  48 /*
  49  * Add listener addresses to the loop configuration.
  50  *
  51  * Arguments:
  52  *
  53  * - default_port
  54  *      The port for the sockets if not specified in addresses.
  55  * - addresses
  56  *      The optional addresses for the listener sockets.  Pass NULL for the
  57  *      wildcard address.  Addresses may be delimited by the characters in
  58  *      ADDRESSES_DELIM.  Addresses are parsed with k5_parse_host_string().
  59  * - prognum, versnum, dispatchfn
  60  *      For RPC listener sockets, the svc_register() arguments to use when new
  61  *      TCP connections are created.
  62  */
  63 krb5_error_code loop_add_udp_address(int default_port, const char *addresses);
  64 krb5_error_code loop_add_tcp_address(int default_port, const char *addresses);
  65 krb5_error_code loop_add_rpc_service(int default_port, const char *addresses,
  66                                      u_long prognum, u_long versnum,
  67                                      void (*dispatchfn)());
  68
  69 krb5_error_code loop_setup_network(verto_ctx *ctx, void *handle,
  70                                    const char *progname,
  71                                    int tcp_listen_backlog);
  72 krb5_error_code loop_setup_signals(verto_ctx *ctx, void *handle,
  73                                    void (*reset)());
  74 void loop_free(verto_ctx *ctx);
  75
  76 /* to be supplied by the server application */
  77
  78 /*
  79  * Two routines for processing an incoming message and getting a
  80  * result to send back.
  81  *
  82  * The first, dispatch(), is for normal processing of a request.  The
  83  * second, make_toolong_error(), is obviously for generating an error
  84  * to send back when the incoming message is bigger than
  85  * the main loop can accept.
  86  */
  87 typedef void (*loop_respond_fn)(void *arg, krb5_error_code code,
  88                                 krb5_data *response);
  89 void dispatch(void *handle, const krb5_fulladdr *local_addr,
  90               const krb5_fulladdr *remote_addr, krb5_data *request,
  91               int is_tcp, verto_ctx *vctx, loop_respond_fn respond, void *arg);
  92 krb5_error_code make_toolong_error (void *handle, krb5_data **);
  93
  94 /*
  95  * Contexts are needed in lots of places.  Opaque application-provided
  96  * handles are passed around in lots of place, but contexts are not.
  97  * For now, we'll require that the application provide us an easy way
  98  * to get at a context; eventually it should probably be explicity.
  99  */
 100 krb5_context get_context(void *handle);
 101
 102 #endif /* NET_SERVER_H */