/* begincopyright
  Copyright (c) 1988 Xerox Corporation. All rights reserved.
  Use and copying of this software and preparation of derivative works based
  upon this software are permitted. Any distribution of this software or
  derivative works must comply with all applicable United States export
  control laws. This software is made available AS IS, and Xerox Corporation
  makes no warranty about the software, its performance or its conformity to
  any specification. Any person obtaining a copy of this software is requested
  to send their name and post office or electronic mail address to:
    PCR Coordinator
    Xerox PARC
    3333 Coyote Hill Rd.
    Palo Alto, CA 94304
  endcopyright */

/*
 * CirioNubInstall.h
 *
 * Demers, November 2, 1989 10:11:22 am PST
 *
 * Primitives used to install CirioNub.
 */

#ifndef _CIRIO_NUB_INSTALL_
#define _CIRIO_NUB_INSTALL_

#include "xr/Threads.h"
#include "xr/CirioNubProtocol.h"


/*
 * Types
 */

typedef char * CirioNubHandle;
/*
    (opaque) handle for CirioNub server
*/

typedef CirioNubRetCode
(*CirioNubProc)(/* int argc, unsigned *args */);
/*
    Proc invoked from other side.
    It runs on a slave IOP, not in a thread, so it can't acquire
        locks (which implies it can't allocate memory, do I/O, ...).
    Calling and called (this) procedure must agree on number and type
        of args.
    Return results by calling the marshalling procedures (CirioNubMarshall.h)
        and returning the appropriate CirioNubRetCode value.
*/

typedef void
(*CirioNubInitProc)(/* void * clientData */);
/*
    Initialization proc for CirioNub.
    Called on slave IOP before creating listener.
*/


/*
 * Public procs
 */

extern int
CirioNubRegisterCProc(/* CirioNubHandle h, int procID, CirioNubProc proc */);
/*
    Register a C procedure with given procID.
    Handle h may already have been installed, or not.
    Return 0 on success, (-1) on failure.
*/


extern int
CirioNubRegisterMProc(/* CirioNubHandle h, int procID, XR_MesaProc mp */);
/*
    Analogous to CirioNubRegisterCProc, but registers a Mesa proc.
*/


extern CirioNubHandle
CirioNubGetDefaultHandle(/* int maxProcs, int callBufBytes */);
/*
    There's a "default" shared CirioNubHandle.
    This behaves like a registration interface -- language runtimes
      acquire the default handle and export (register) their
      language-specific CirioNubProcs through it.
    See CirioNubCreateHandle below.
*/



/*
 * Friend procs
 */


extern CirioNubHandle
CirioNubCreateHandle(/* int maxProcs, int callBufBytes */);
/*
    Create a CirioNub handle and return it.
    Parameters are max number of procs that can be registered with this handle
        and max number of bytes of arguments that can be processed.
    Reserve a slave IOP for the handle to execute in.
    Return NIL on failure.
*/


extern int
CirioNubInstall(/*
    CirioNubHandle h,
    unsigned listenerPort,
    CirioNubInitProc initProc,
    void *clientData
*/);
/*
    Install debug nub with procedures registered with handle h
        listening at given TCP port.
    If port is 0, well-known default port is used.
    The initProc(clientData) is called in the slave IOP before the listener
        is created.
    Attempting to install a handle a second time succeeds but is a no-op.
*/


#endif /* _CIRIO_NUB_INSTALL_ */