libpkg (Network Communications)

Files
file	pkg.h

Data Structures
struct	pkg_switch
struct	pkg_header
struct	pkg_conn

Macros
#define	PKG_STDIO_MODE   -3
#define	PKG_MAGIC   0x41FE
#define	PKG_STREAMLEN   (32*1024)
#define	PKC_NULL   ((struct pkg_conn *)0)
#define	PKC_ERROR   ((struct pkg_conn *)(-1L))
#define	pkg_send_vls(type, vlsp, pkg)    pkg_send( (type), bu_vls_addr((vlsp)), bu_vls_strlen((vlsp))+1, (pkg) )

Typedefs
typedef void(*	pkg_callback) (struct pkg_conn *, char *)
typedef void(*	pkg_errlog) (const char *msg)

Functions
struct pkg_conn *	pkg_open (const char *host, const char *service, const char *protocol, const char *username, const char *passwd, const struct pkg_switch *switchp, pkg_errlog errlog)
void	pkg_close (struct pkg_conn *pc)
int	pkg_process (struct pkg_conn *)
int	pkg_suckin (struct pkg_conn *)
int	pkg_send (int type, const char *buf, size_t len, struct pkg_conn *pc)
int	pkg_2send (int type, const char *buf1, size_t len1, const char *buf2, size_t len2, struct pkg_conn *pc)
int	pkg_stream (int type, const char *buf, size_t len, struct pkg_conn *pc)
int	pkg_flush (struct pkg_conn *pc)
int	pkg_waitfor (int type, char *buf, size_t len, struct pkg_conn *pc)
char *	pkg_bwaitfor (int type, struct pkg_conn *pc)
int	pkg_block (struct pkg_conn *pc)
struct pkg_conn *	pkg_transerver (const struct pkg_switch *switchp, pkg_errlog errlog)
int	pkg_permserver (const char *service, const char *protocol, int backlog, pkg_errlog)
int	pkg_permserver_ip (const char *ipOrHostname, const char *service, const char *protocol, int backlog, pkg_errlog errlog)
struct pkg_conn *	pkg_getclient (int fd, const struct pkg_switch *switchp, pkg_errlog errlog, int nodelay)
unsigned short	pkg_gshort (char *buf)
unsigned long	pkg_glong (char *buf)
char *	pkg_pshort (char *buf, unsigned short s)
char *	pkg_plong (char *buf, unsigned long l)
const char *	pkg_version (void)

Variables
int	pkg_permport

Detailed Description

Macro Definition Documentation

PKG_STDIO_MODE

#define PKG_STDIO_MODE   -3

Definition at line 54 of file pkg.h.

PKG_MAGIC

#define PKG_MAGIC   0x41FE

Format of the message header as it is transmitted over the network connection. Internet network order is used. User Code should access pkc_len and pkc_type rather than looking into the header directly. Users should never need to know what this header looks like.

Definition at line 78 of file pkg.h.

PKG_STREAMLEN

#define PKG_STREAMLEN   (32*1024)

Definition at line 85 of file pkg.h.

PKC_NULL

#define PKC_NULL   ((struct pkg_conn *)0)

Definition at line 112 of file pkg.h.

PKC_ERROR

#define PKC_ERROR   ((struct pkg_conn *)(-1L))

Definition at line 113 of file pkg.h.

pkg_send_vls

#define pkg_send_vls	(		type,
			vlsp,
			pkg
	)		pkg_send( (type), bu_vls_addr((vlsp)), bu_vls_strlen((vlsp))+1, (pkg) )

Sends a VLS as a given message type across a pkg connection.

Definition at line 119 of file pkg.h.

Typedef Documentation

pkg_callback

typedef void(* pkg_callback) (struct pkg_conn *, char *)

Definition at line 61 of file pkg.h.

pkg_errlog

typedef void(* pkg_errlog) (const char *msg)

Definition at line 62 of file pkg.h.

Function Documentation

pkg_open()

struct pkg_conn * pkg_open	(	const char *	host,
		const char *	service,
		const char *	protocol,
		const char *	username,
		const char *	passwd,
		const struct pkg_switch *	switchp,
		pkg_errlog	errlog
	)

Open a network connection to a host/server.

Returns PKC_ERROR on error.

pkg_close()

void pkg_close

(

struct pkg_conn *

pc

)

Close a network connection.

Gracefully release the connection block and close the connection.

pkg_process()

int pkg_process

(

struct pkg_conn *

)

pkg_suckin()

int pkg_suckin

(

struct pkg_conn *

)

Suck all data from the operating system into the internal buffer.

This is done with large buffers, to maximize the efficiency of the data transfer from kernel to user.

It is expected that the read() system call will return as much data as the kernel has, UP TO the size indicated. The only time the read() may be expected to block is when the kernel does not have any data at all. Thus, it is wise to call call this routine only if:

 a)  select() has indicated the presence of data, or
 b)  blocking is acceptable.

This routine is the only place where data is taken off the network. All input is appended to the internal buffer for later processing.

Subscripting was used for pkc_incur/pkc_inend to avoid having to recompute pointers after a realloc().

Returns - -1 on error 0 on EOF 1 success

pkg_send()

int pkg_send	(	int	type,
		const char *	buf,
		size_t	len,
		struct pkg_conn *	pc
	)

Send a message on the connection.

Send the user's data, prefaced with an identifying header which contains a message type value. All header fields are exchanged in "network order".

Note that the whole message (header + data) should be transmitted by TCP with only one TCP_PUSH at the end, due to the use of writev().

Returns number of bytes of user data actually sent.

pkg_2send()

int pkg_2send	(	int	type,
		const char *	buf1,
		size_t	len1,
		const char *	buf2,
		size_t	len2,
		struct pkg_conn *	pc
	)

Send a two part message on the connection.

Exactly like pkg_send, except user's data is located in two disjoint buffers, rather than one. Fiendishly useful!

pkg_stream()

int pkg_stream	(	int	type,
		const char *	buf,
		size_t	len,
		struct pkg_conn *	pc
	)

Send a message that doesn't need a push.

Exactly like pkg_send except no "push" is necessary here. If the packet is sufficiently small (MAXQLEN) it will be placed in the pkc_stream buffer (after flushing this buffer if there insufficient room). If it is larger than this limit, it is sent via pkg_send (who will do a pkg_flush if there is already data in the stream queue).

Returns number of bytes of user data actually sent (or queued).

pkg_flush()

int pkg_flush

(

struct pkg_conn *

pc

)

Empty the stream buffer of any queued messages.

Flush any pending data in the pkc_stream buffer.

Returns < 0 on failure, else number of bytes sent.

pkg_waitfor()

int pkg_waitfor	(	int	type,
		char *	buf,
		size_t	len,
		struct pkg_conn *	pc
	)

Wait for a specific msg, user buf, processing others.

This routine implements a blocking read on the network connection until a message of 'type' type is received. This can be useful for implementing the synchronous portions of a query/reply exchange. All messages of any other type are processed by pkg_block().

Returns the length of the message actually received, or -1 on error.

pkg_bwaitfor()

char * pkg_bwaitfor	(	int	type,
		struct pkg_conn *	pc
	)

Wait for specific msg, malloc buf, processing others.

This routine implements a blocking read on the network connection until a message of 'type' type is received. This can be useful for implementing the synchronous portions of a query/reply exchange. All messages of any other type are processed by pkg_block().

The buffer to contain the actual message is acquired via malloc(), and the caller must free it.

Returns pointer to message buffer, or NULL.

pkg_block()

int pkg_block

(

struct pkg_conn *

pc

)

Wait until a full message has been read.

This routine blocks, waiting for one complete message to arrive from the network. The actual handling of the message is done with _pkg_dispatch(), which invokes the user-supplied message handler.

This routine can be used in a loop to pass the time while waiting for a flag to be changed by the arrival of an asynchronous message, or for the arrival of a message of uncertain type.

The companion routine is pkg_process(), which does not block.

Control returns to the caller after one full message is processed. Returns -1 on error, etc.

pkg_transerver()

struct pkg_conn * pkg_transerver	(	const struct pkg_switch *	switchp,
		pkg_errlog	errlog
	)

Become a transient network server

Become a one-time server on a given open connection. A client has already called and we have already answered. This will be a servers starting condition if he was created by a process like the UNIX inetd.

Returns PKC_ERROR or a pointer to a pkg_conn structure.

pkg_permserver()

int pkg_permserver	(	const char *	service,
		const char *	protocol,
		int	backlog,
		pkg_errlog
	)

Create a network server, and listen for connection.

We are now going to be a server for the indicated service. Hang a LISTEN, and return the fd to select() on waiting for new connections.

Returns fd to listen on (>=0), -1 on error.

pkg_permserver_ip()

int pkg_permserver_ip	(	const char *	ipOrHostname,
		const char *	service,
		const char *	protocol,
		int	backlog,
		pkg_errlog	errlog
	)

Create network server from IP address, and listen for connection.

We are now going to be a server for the indicated service. Hang a LISTEN, and return the fd to select() on waiting for new connections.

Returns fd to listen on (>=0), -1 on error.

pkg_getclient()

struct pkg_conn * pkg_getclient	(	int	fd,
		const struct pkg_switch *	switchp,
		pkg_errlog	errlog,
		int	nodelay
	)

As permanent network server, accept a new connection

Given an fd with a listen outstanding, accept the connection. When poll == 0, accept is allowed to block. When poll != 0, accept will not block.

Returns - >0 ptr to pkg_conn block of new connection PKC_NULL accept would block, try again later PKC_ERROR fatal error

pkg_gshort()

unsigned short pkg_gshort

(

char *

buf

)

Get a 16-bit short from a char[2] array

pkg_glong()

unsigned long pkg_glong

(

char *

buf

)

Get a 32-bit long from a char[4] array

pkg_pshort()

char * pkg_pshort	(	char *	buf,
		unsigned short	s
	)

Put a 16-bit short into a char[2] array

pkg_plong()

char * pkg_plong	(	char *	buf,
		unsigned long	l
	)

Put a 32-bit long into a char[4] array

pkg_version()

const char * pkg_version

(

void

)

returns a human-readable string describing this version of the LIBPKG library.

Variable Documentation

pkg_permport

int pkg_permport

extern