/* * Mach Operating System * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University * All Rights Reserved. * * Permission to use, copy, modify and distribute this software and its * documentation is hereby granted, provided that both the copyright * notice and this permission notice appear in all copies of the * software, derivative works or modified versions, and any portions * thereof, and that both notices appear in supporting documentation. * * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. * * Carnegie Mellon requests users of this software to return to * * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU * School of Computer Science * Carnegie Mellon University * Pittsburgh PA 15213-3890 * * any improvements or extensions that they make and grant Carnegie Mellon * the rights to redistribute these changes. */ #ifndef _NW_H_ #define _NW_H_ 1 #if defined(KMODE) || defined(KERNEL) #include #include #else #include "stub0.h" #endif /*** NETWORK APPLICATION PROGRAMMING INTERFACE ***/ /*** TYPES ***/ typedef enum { NW_SUCCESS, NW_FAILURE, NW_BAD_ADDRESS, NW_OVERRUN, NW_NO_CARRIER, NW_NOT_SERVER, NW_NO_EP, NW_BAD_EP, NW_INVALID_ARGUMENT, NW_NO_RESOURCES, NW_PROT_VIOLATION, NW_BAD_BUFFER, NW_BAD_LENGTH, NW_NO_REMOTE_EP, NW_TIME_OUT, NW_INCONSISTENCY, NW_ABORTED, NW_SYNCH, NW_QUEUED } nw_result, *nw_result_t; typedef enum { NW_INITIALIZE, NW_HOST_ADDRESS_REGISTER, NW_HOST_ADDRESS_UNREGISTER } nw_update_type; typedef enum { NW_STATUS, NW_HOST_ADDRESS_LOOKUP } nw_lookup_type; typedef u_int ip_address; typedef u_int nw_address_1; typedef u_int nw_address_2; typedef struct { char name[20]; /*Host name -- first 19 characters, zero-terminated*/ ip_address ip_addr; nw_address_1 nw_addr_1; /*4 most significant bits specify the device*/ nw_address_2 nw_addr_2; } nw_address_s, *nw_address_t; typedef enum { NW_NULL, NW_IP, /*Virtual network for IP addresses*/ NW_TCA100_1, /*Fore Systems ATM network, first unit*/ NW_TCA100_2 /*Fore Systems ATM network, second unit*/ } nw_device, *nw_device_t; #define NW_DEVICE(addr) (addr >> 28) typedef u_int nw_ep, *nw_ep_t; typedef enum { NW_RAW, /*Raw service provided by network*/ NW_DATAGRAM, /*Connectionless service*/ NW_SEQ_PACKET, /*Connection-oriented service*/ NW_LINE /*Multiplexing line (system use only)*/ } nw_protocol; typedef enum { NW_NO_ACCEPT, /*Connection requests not accepted (client)*/ NW_APPL_ACCEPT, /*Connection requests received as message by application (msg_seqno 0), for examination and approval (nw_connection_accept function)*/ NW_AUTO_ACCEPT, /*Connection requests automatically accepted if endpoint is connection-oriented and not already connected*/ NW_LINE_ACCEPT /*Connection requests automatically accepted on a new endpoint (system use only)*/ } nw_acceptance; typedef struct { nw_address_1 rem_addr_1; nw_address_2 rem_addr_2; nw_ep remote_ep:16; nw_ep local_ep:16; } nw_peer_s, *nw_peer_t; typedef struct nw_buffer { u_int buf_used:1; /*Read-only for applications (always 1)*/ u_int buf_length:31; /*Read-only for applications*/ struct nw_buffer *buf_next; /*Used only to gather on sends*/ u_int msg_seqno:10; /*Sequential number of message, automatically set by network interface*/ u_int block_offset:22; /*Offset to the beginning of data (in bytes), from the start of the buffer*/ u_int block_deallocate:1; /*Used only to deallocate on sends*/ u_int block_length:31; /*Length of data (in bytes) beginning at offset*/ nw_peer_s peer; /*Set on receives. Also required in first block on datagram sends. Ignored on sequenced packet sends.*/ } nw_buffer_s, *nw_buffer_t; /* msg_seqno is normally between 1 and 1023, and increases modulo 1024 (skipping 0) between consecutive messages. In sequenced packets, msg_seqno increases strictly by one. msg_seqno is assigned automatically. The network interface writes in the buffer the msg_seqno used, but only after the buffer has been transmitted and, in case of sequenced packet, acknowledged. The application can use this update to determine if a buffer can be reused, after a sending a message without the deallocate option. msg_seqno 0 is used when the corresponding send specifies the NW_URGENT option. Such messages bypass any other messages possibly enqueued. msg_seqno 0 is also used for open connection requests, in the case of sequenced packet endpoints with the NW_APPL_ACCEPT option. The type of msg_seqno 0 message is differentiated by the first word in the message, which has type nw_options */ #define NW_BUFFER_ERROR ((nw_buffer_t) -1) /*Used for error indication other than buffer overrun (for which NULL is used)*/ typedef enum { NW_INEXISTENT, NW_UNCONNECTED, NW_SIMPLEX_ORIGINATING, NW_SIMPLEX_ORIGINATED, NW_DUPLEX_ORIGINATING, NW_DUPLEX_ORIGINATING_2, NW_DUPLEX_ORIGINATED, NW_ORIGINATOR_CLOSING, NW_ORIGINATOR_RCLOSING, NW_ACCEPTING, NW_SIMPLEX_ACCEPTED, NW_DUPLEX_ACCEPTING, NW_DUPLEX_ACCEPTED, NW_ACCEPTOR_CLOSING, NW_ACCEPTOR_RCLOSING } nw_state, *nw_state_t; typedef enum nw_options { NW_NORMAL, NW_URGENT, NW_SYNCHRONIZATION /*System use only*/ } nw_options; /*** FUNCTIONS ***/ extern nw_result nw_update(mach_port_t master_port, nw_update_type up_type, int *up_info); /***************************************************************************** Allows privileged applications to update network tables. The application must present the device master port. up_type selects the type of update, and up_info is cast accordingly to the correct type. For NW_HOST_ADDRESS_REGISTER and NW_HOST_ADDRESS_UNREGISTER, up_info has type nw_address_t. For NW_HOST_ADDRESS_UNREGISTER, however, only the network address field is used. up_info is not used for NW_INITIALIZE. This option is used to initialize network interface tables, but does not initialize devices. Initialization of hardware and network tables occurs automatically at probe/boot time, so this option is normally unnecessary. Returns NW_SUCCESS if operation completed successfully. NW_FAILURE if master port not presented. NW_NO_RESOURCES if network tables full (NW_HOST_ADDRESS_REGISTER). NW_BAD_ADDRESS if host not found (NW_HOST_ADDRESS_UNREGISTER). NW_INVALID_ARGUMENT if up_type is invalid or up_info is a bad pointer. *****************************************************************************/ extern nw_result nw_lookup(nw_lookup_type lt, int *look_info); /***************************************************************************** Allows applications to lookup network tables. The type of lookup is selected by lt, and look_info is cast to the correct type accordingly. For lt equal to NW_HOST_ADDRESS_LOOKUP, look_info has type nw_address_t. In this option, the host is looked up first using the IP address as a key (if non-zero), then by name (if non-empty), and finally by network address (if non-zero). The function returns NW_SUCCESS on the first match it finds, and sets the non-key fields of look_info to the values found. No consistency check is made if more than one key is supplied. The function returns NW_BAD_ADDRESS if the host was not found, and NW_INVALID_ARGUMENT if lt is invalid or look_info is a bad pointer. For lt equal to NW_STATUS, look_info has type nw_device_t on input and nw_result_t on output. The function returns NW_INVALID_ARGUMENT if the device chosen is invalid or look_info is a bad pointer; otherwise, the function returns NW_SUCCESS. look_info is set to: NW_FAILURE if the device is not present, NW_NOT_SERVER if the device is not serviced by this interface, or a device-dependent value otherwise (NW_SUCCESS if there is no device error). *****************************************************************************/ extern nw_result nw_endpoint_allocate(nw_ep_t epp, nw_protocol protocol, nw_acceptance accept, u_int buffer_size); /***************************************************************************** Allocates a communication endpoint. On input, epp should point to the the endpoint number desired, or to 0 if any number is adequate. On output, epp points to the actual number allocated for the endpoint. protocol specifies the transport discipline applied to data transmitted or received through the endpoint. accept selects how open connection requests received for the endpoint should be handled (connection-oriented protocol), or whether the endpoint can receive messages (connectionless protocol). buffer_size specifies the length in bytes of the buffer area for data sent or received through the endpoint. Returns NW_SUCCESS if endpoint successfully allocated. NW_INVALID_ARGUMENT if epp is a bad pointer or the protocol or accept arguments are invalid. NW_NO_EP if the endpoint name space is exhausted. NW_BAD_EP if there already is an endpoint with the number selected, or the number selected is out of bounds. NW_NO_RESOURCES if not enough memory for buffer. *****************************************************************************/ extern nw_result nw_endpoint_deallocate(nw_ep ep); /***************************************************************************** Deallocates the given endpoint. Returns NW_SUCCESS if successfully deallocated endpoint. NW_BAD_EP if endpoint does not exist. NW_PROT_VIOLATION if access to endpoint not authorized. *****************************************************************************/ extern nw_buffer_t nw_buffer_allocate(nw_ep ep, u_int size); /***************************************************************************** Allocates a buffer of the given size (in bytes) from the buffer area of the given endpoint. Returns NW_BUFFER_ERROR if endpoint does not exist or access to endpoint is not authorized. NULL if no buffer with given size could be allocated. Pointer to allocated buffer, otherwise. *****************************************************************************/ extern nw_result nw_buffer_deallocate(nw_ep ep, nw_buffer_t buffer); /***************************************************************************** Deallocates the given buffer. Returns NW_SUCCESS if successfully deallocated buffer. NW_BAD_EP if endpoint does not exist. NW_PROT_VIOLATION if access to endpoint not authorized. NW_BAD_BUFFER if buffer does not belong to endpoint's buffer area or is malformed. *****************************************************************************/ extern nw_result nw_connection_open(nw_ep local_ep, nw_address_1 rem_addr_1, nw_address_2 rem_addr_2, nw_ep remote_ep); /***************************************************************************** Opens a connection. Returns NW_SUCCESS if connection successfully opened. NW_BAD_EP if local endpoint does not exist, uses connectionless protocol or is already connected. NW_PROT_VIOLATION if access to local or remote endpoint not authorized. NW_BAD_ADDRESS if address of remote host is invalid. NW_NO_REMOTE_EP if connection name space exhausted at remote host. NW_TIME_OUT if attempt to open connection timed out repeatedly. NW_FAILURE if remote endpoint does not exist, uses connectionless protocol or is already connected, or if remote application did not accept open request. *****************************************************************************/ extern nw_result nw_connection_accept(nw_ep ep, nw_buffer_t msg, nw_ep_t new_epp); /***************************************************************************** Accepts open request (at the remote host). On input, new_epp equal to NULL indicates that the application does not accept the request. new_epp pointing to the value 0 indicates that the application wants to accept the connection on a new endpoint, created dynamically, with the same attributes as the original endpoint; new_epp pointing to the value ep indicates that the application wants to simply accept the open request. On output, new_epp points to the endpoint actually connected, if any. msg points to the open request, which is automatically deallocated. Returns NW_SUCCESS if connection correctly accepted or refused. NW_BAD_EP if endpoint does not exist or has no outstanding open request. NW_PROT_VIOLATION if access to endpoint not authorized. NW_BAD_BUFFER if msg does not belong to the endpoint's buffer area, or is malformed. NW_INVALID_ARGUMENT if new_epp is a bad pointer or points to invalid value. NW_NO_EP if endpoint name space exhausted. NW_NO_RESOURCES if no buffer available for new endpoint. NW_TIME_OUT if attempt to accept at different endpoint repeatedly timed out. *****************************************************************************/ extern nw_result nw_connection_close(nw_ep ep); /***************************************************************************** Closes the endpoint's connection. Returns NW_SUCCESS if successfully closed connection. NW_BAD_EP if endpoint does not exist or is not connected. NW_PROT_VIOLATION if access to endpoint not authorized. *****************************************************************************/ extern nw_result nw_multicast_add(nw_ep local_ep, nw_address_1 rem_addr_1, nw_address_2 rem_addr_2, nw_ep remote_ep); /***************************************************************************** Open multicast group or add one more member to multicast group. Returns NW_SUCCESS if successfully opened multicast group or added member. NW_BAD_EP if local endpoint does not exist, uses connectionless protocol or is already connected point-to-point. NW_PROT_VIOLATION if access to local or remote endpoint not authorized. NW_BAD_ADDRESS if address of remote host is invalid. NW_NO_REMOTE_EP if connection name space exhausted at remote host. NW_TIME_OUT if attempt to open or add to multicast timed out repeatedly. NW_FAILURE if remote endpoint does not exist, uses connectionless protocol or is already connected, or if remote application did not accept open or add request. *****************************************************************************/ extern nw_result nw_multicast_drop(nw_ep local_ep, nw_address_1 rem_addr_1, nw_address_2 rem_addr_2, nw_ep remote_ep); /***************************************************************************** Drop member from multicast group, or close group if last member. Returns NW_SUCCESS if successfully dropped member or closed group. NW_BAD_EP if local endpoint does not exist or is not connected in multicast to the given remote endpoint. NW_PROT_VIOLATION if access to local endpoint not authorized. *****************************************************************************/ extern nw_result nw_endpoint_status(nw_ep ep, nw_state_t state, nw_peer_t peer); /***************************************************************************** Returns the state of the given endpoint and peer to which it is connected, if any. In case of multicast group, the first peer is returned. Returns NW_SUCCESS if status correctly returned. NW_BAD_EP if endpoint does not exist. NW_PROT_VIOLATION if access to endpoint not authorized. NW_INVALID_ARGUMENT if state or peer is a bad pointer. *****************************************************************************/ extern nw_result nw_send(nw_ep ep, nw_buffer_t msg, nw_options options); /***************************************************************************** Sends message through endpoint with the given options. Returns NW_SUCCESS if message successfully queued for sending (connectionless protocol) or sent and acknowledged (connection-oriented protocol). NW_BAD_EP if endpoint does not exist or uses connection-oriented protocol but is unconnected. NW_PROT_VIOLATION if access to endpoint not authorized. NW_BAD_BUFFER if msg (or one of the buffers linked by buf_next) is not a buffer in the endpoint's buffer area, or is malformed (e.g., block_length extends beyond end of buffer). NW_NO_RESOURCES if unable to queue message due to resource exhaustion. NW_BAD_LENGTH if the total message length is too long for the network and protocol used. NW_BAD_ADDRESS if address of remote host is invalid (connectionless protocol). NW_FAILURE if repeated errors in message transmission (connection-oriented). NW_TIME_OUT if repeated time-outs in message transmission (connection-oriented). NW_OVERRUN if no buffer available in receiver's buffer area. (connection-oriented). *****************************************************************************/ extern nw_buffer_t nw_receive(nw_ep ep, int time_out); /***************************************************************************** Receive message destined to endpoint. Return if request not satisfied within time_out msec. time_out 0 means non-blocking receive, while -1 means block indefinitely. Returns NW_BUFFER_ERROR if endpoint does not exist or access to endpoint is not authorized. NULL if no message available for reception within the specified time-out period. Pointer to message, otherwise. *****************************************************************************/ extern nw_buffer_t nw_rpc(nw_ep ep, nw_buffer_t send_msg, nw_options options, int time_out); /***************************************************************************** Send message through given endpoint with given options and then receive message through the same endpoint. Receive waiting time is limited to time_out msec. Returns NW_BUFFER_ERROR if endpoint does not exist, access to endpoint is not authorized, or there was some transmission error. NULL if no message available for reception within the specified time-out period. Pointer to message received, otherwise. *****************************************************************************/ extern nw_buffer_t nw_select(u_int nep, nw_ep_t epp, int time_out); /***************************************************************************** Receive message from one of the nep endpoints in the array epp. Waiting time is limited to time_out msec. Returns NW_BUFFER_ERROR if epp does not point to a valid array of nep endpoint numbers, one of the endpoints does not exist or has restricted access or the request could not be correctly queued because of resource exhaustion. NULL if no message arrived within the specified time-out period. Pointer to message received, otherwise. *****************************************************************************/ #endif /* _NW_H_ */