BRL-CAD
libpkg (pkg)

Files

file  pkg.h
 

Data Structures

struct  pkg_switch
 
struct  pkg_header
 
struct  pkg_conn
 

Macros

#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_connpkg_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_connpkg_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_connpkg_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)
 

Detailed Description

Macro Definition Documentation

#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 71 of file pkg.h.

Referenced by pkg_2send(), pkg_send(), and pkg_stream().

#define PKG_STREAMLEN   (32*1024)

Definition at line 78 of file pkg.h.

Referenced by pkg_send(), pkg_stream(), and pkg_suckin().

#define PKC_NULL   ((struct pkg_conn *)0)

Definition at line 103 of file pkg.h.

Referenced by drop_client(), pkg_getclient(), and run_server().

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

Definition at line 104 of file pkg.h.

Referenced by fbs_rfbpoll(), new_client(), pkg_getclient(), pkg_open(), rem_open(), run_client(), and run_server().

#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 110 of file pkg.h.

Typedef Documentation

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

Definition at line 54 of file pkg.h.

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

Definition at line 55 of file pkg.h.

Function Documentation

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.

Referenced by rem_open(), and run_client().

void pkg_close ( struct pkg_conn pc)

Close a network connection.

Gracefully release the connection block and close the connection.

Definition at line 800 of file pkg.c.

References MAX_PKG_ERRBUF_SIZE, pkg_conn::pkc_buf, pkg_conn::pkc_errlog, pkg_conn::pkc_fd, pkg_conn::pkc_inbuf, pkg_conn::pkc_inlen, pkg_conn::pkc_magic, pkg_conn::pkc_strpos, PKG_CK, and pkg_flush().

Referenced by drop_client(), new_client(), rem_close(), rem_free(), run_client(), and run_server().

Here is the call graph for this function:

int pkg_process ( struct pkg_conn )
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

Definition at line 1715 of file pkg.c.

References MAX_PKG_ERRBUF_SIZE, out, pkg_conn::pkc_errlog, pkg_conn::pkc_fd, pkg_conn::pkc_inbuf, pkg_conn::pkc_incur, pkg_conn::pkc_inend, pkg_conn::pkc_inlen, PKG_CK, PKG_READ, and PKG_STREAMLEN.

Referenced by existing_client_handler(), run_client(), and run_server().

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.

Definition at line 934 of file pkg.c.

References MAX_PKG_ERRBUF_SIZE, MAXQLEN, pkg_conn::pkc_errlog, pkg_conn::pkc_fd, pkg_conn::pkc_strpos, PKG_CK, pkg_flush(), PKG_MAGIC, pkg_plong(), pkg_pshort(), PKG_SEND, pkg_stream(), PKG_STREAMLEN, pkg_header::pkh_len, pkg_header::pkh_magic, and pkg_header::pkh_type.

Referenced by fbs_rfbbwreadrect(), fbs_rfbbwwriterect(), fbs_rfbclear(), fbs_rfbclose(), fbs_rfbcursor(), fbs_rfbflush(), fbs_rfbfree(), fbs_rfbgetcursor(), fbs_rfbgetview(), fbs_rfbhelp(), fbs_rfbopen(), fbs_rfbread(), fbs_rfbreadrect(), fbs_rfbrmap(), fbs_rfbscursor(), fbs_rfbsetcursor(), fbs_rfbview(), fbs_rfbwindow(), fbs_rfbwmap(), fbs_rfbwrite(), fbs_rfbwriterect(), fbs_rfbzoom(), pkg_stream(), rem_bwreadrect(), rem_clear(), rem_close(), rem_cursor(), rem_flush(), rem_free(), rem_getcursor(), rem_getview(), rem_help(), rem_open(), rem_poll(), rem_read(), rem_readrect(), rem_rmap(), rem_view(), rem_wmap(), run_client(), and run_server().

Here is the call graph for this function:

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!

Definition at line 1061 of file pkg.c.

References MAX_PKG_ERRBUF_SIZE, pkg_conn::pkc_errlog, pkg_conn::pkc_fd, pkg_conn::pkc_strpos, PKG_CK, pkg_flush(), PKG_MAGIC, pkg_plong(), pkg_pshort(), PKG_SEND, pkg_header::pkh_len, pkg_header::pkh_magic, and pkg_header::pkh_type.

Referenced by rem_bwwriterect(), rem_setcursor(), rem_write(), and rem_writerect().

Here is the call graph for this function:

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).

Definition at line 1210 of file pkg.c.

References MAXQLEN, pkg_conn::pkc_stream, pkg_conn::pkc_strpos, pkg_flush(), PKG_MAGIC, pkg_plong(), pkg_pshort(), pkg_send(), PKG_STREAMLEN, pkg_header::pkh_len, pkg_header::pkh_magic, and pkg_header::pkh_type.

Referenced by pkg_send().

Here is the call graph for this function:

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.

Definition at line 1243 of file pkg.c.

References MAX_PKG_ERRBUF_SIZE, pkg_conn::pkc_errlog, pkg_conn::pkc_fd, pkg_conn::pkc_stream, and pkg_conn::pkc_strpos.

Referenced by pkg_2send(), pkg_close(), pkg_send(), and pkg_stream().

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.

Definition at line 1355 of file pkg.c.

References bp, MAX_PKG_ERRBUF_SIZE, pkg_conn::pkc_buf, pkg_conn::pkc_curpos, pkg_conn::pkc_errlog, pkg_conn::pkc_left, pkg_conn::pkc_len, pkg_conn::pkc_type, pkg_block(), and PKG_CK.

Referenced by rem_bwreadrect(), rem_clear(), rem_close(), rem_cursor(), rem_flush(), rem_free(), rem_getcursor(), rem_getview(), rem_help(), rem_open(), rem_read(), rem_readrect(), rem_rmap(), rem_view(), and rem_wmap().

Here is the call graph for this function:

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.

Definition at line 1448 of file pkg.c.

References MAX_PKG_ERRBUF_SIZE, pkg_conn::pkc_buf, pkg_conn::pkc_curpos, pkg_conn::pkc_errlog, pkg_conn::pkc_left, pkg_conn::pkc_len, pkg_conn::pkc_type, pkg_block(), and PKG_CK.

Referenced by run_server().

Here is the call graph for this function:

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.

Definition at line 1682 of file pkg.c.

References pkg_conn::pkc_curpos, pkg_conn::pkc_left, and PKG_CK.

Referenced by pkg_bwaitfor(), and pkg_waitfor().

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.

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.

Referenced by fbs_open(), and run_server().

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.

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

Referenced by new_client_handler(), and run_server().

unsigned short pkg_gshort ( char *  buf)

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

Definition at line 157 of file pkg.c.

References OSL::Strings::u.

Referenced by fbs_rfbwmap().

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

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

Definition at line 181 of file pkg.c.

References s.

Referenced by fbs_rfbrmap(), pkg_2send(), pkg_send(), and pkg_stream().

const char* pkg_version ( void  )

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

returns the compile-time version of libpkg

Definition at line 31 of file vers.c.