# Ocamlnet 2 Reference Manual

Ocamlnet consists of a number of libraries:

- `netstring` is about processing strings that occur in network context
- `netcgi1` and `netcgi2` focus on portable web applications
- `nethttpd` is a web server component (HTTP server implementation)
- `netplex` is a generic server framework
- `rpc` implements OncRPC
- `netclient` implements clients for HTTP, FTP, and Telnet
- `equeue` is an event queue used for many protocol implementations
- `shell` is about calling external commands
- `netshm` provides shared memory for IPC purposes
- `netsys` contains bindings for system functions
- `smtp` and `pop` are two further client implementations

A number of ideas and concepts are used throughout the libraries:

- `Netchannels` are a way to abstract sequential I/O channels
- The event queues provided by `Equeue` and `Unixqueue` make asynchronous protocol interpreters possible

## The `netstring` library

`netstring` focuses on string processing functions.

Netconversion | Conversion between character encodings
Netchannels | Object-oriented I/O: Basic types and classes
Netstream | A netstream is an input channel that is read block by block.
Mimestring | Low-level functions to parse and print mail and MIME messages
Netmime | Netmime contains high-level classes and functions to process mail and MIME messages.
Netsendmail | Functions to compose and send electronic mails
Neturl | Uniform Resource Locators (URLs)
Netaddress | Parsing of mail addresses
Netbuffer | A Netbuffer.t is a buffer that can grow and shrink dynamically.
Netdate | Support for common date/time parsing and formatting.
Netencoding | Base64, Quoted Printable, URL encoding, HTML escaping
Netulex | Support module for Alain Frisch's `ulex` lexer generator
Netaccel | Accelerators for bytecode
Netaccel_link | Enables accelerator module `Netaccel`
Nethtml | Parsing of HTML
Nethttp | Basic definitions for the HTTP protocol
Netstring_str | Wrapper for regexps with `Str` syntax
Netstring_pcre | Wrapper for regexps with PCRE syntax
Netstring_mt | Initialisation code for multi-threading
Netmappings | Internal access to the character conversion database
Netaux | Internal auxiliary functions

### Guides

- `Netchannels_tut`: The `Netchannels` tutorial - strongly recommended read!
- `Netmime_tut`: The `Netmime` tutorial
- `Netsendmail_tut`: The `Netsendmail` tutorial
- `Netulex_tut`: The `Netulex` tutorial
- `Neturl_tut`: The `Neturl` tutorial

## The `netcgi1` library

The `netcgi1` library is the old library for writing portable web applications, formerly known as `cgi` (this name is now an alias for `netcgi1`). Its features are frozen. A description of its interfaces can be found here.

Note that it is not possible to use `netcgi1` and `netcgi2` at the same time.

## The `netcgi2` library

This is the revised library for Web applications, now called `netcgi2`.

Netcgi | Common data-structures for CGI-like connectors.
Netcgi_common | Functions to develop new connectors.
Netcgi_cgi | Classical CGI connector.
Netcgi_fcgi | FastCGI connector.
Netcgi_ajp | Apache JServ Protocol (AJP) 1.3 connector.
Netcgi_scgi | SCGI connector.
Netcgi_test | Connector for testing your code.
Netcgi_dbi | Pools of connections for the ocamldbi generic database interface.
Netcgi1_compat | Compatibility module with the previous version of Netcgi.

Note that it is not possible to use `netcgi1` and `netcgi2` at the same time.

### Guides

- `Netcgi_porting`: Porting `netcgi1` programs to `netcgi2`

## The `netcgi2-apache` library

This is an Apache connector for the `netcgi2` library.

Netcgi_apache |
Netcgi_modtpl |

## The `nethttpd` library

The `nethttpd` library is a Web server component written in O'Caml. For a full web server, you'll also need `netplex`.

Nethttpd_types | Type definitions for the HTTP daemon
Nethttpd_kernel | The protocol kernel of the HTTP daemon
Nethttpd_reactor | The reactive encapsulation of the HTTP daemon
Nethttpd_engine | The event-based encapsulation of the HTTP daemon
Nethttpd_services | Service Providers for HTTP daemon
Nethttpd_plex | Netplex support

### Guides

- `Nethttpd_intro`: Overview over the HTTP daemon

## The `netplex` library

The `netplex` library is a protocol-independent server framework. Especially, it can be used in conjunction with `nethttpd` to build web servers, and with `rpc` to build RPC servers.

Netplex_types | Types for `Netplex`
Netplex_config | Read the configuration file
Netplex_controller | Controller
Netplex_container | Containers
Netplex_sockserv | Socket service creation
Netplex_workload | Workload management
Netplex_kit | Netplex toolkit
Netplex_log | Loggers
Netplex_main | Main program for Netplex servers
Netplex_mp | Multi-processing provider
Netplex_mt | Multi-threading provider
Rpc_netplex | Netplex support for RPC servers (TCP only)

### Guides

- `Netplex_intro`: Introduction to `Netplex`

## The `rpc` library

This library implements OncRPC (alias SunRPC).

Rtypes | Basic types
Xdr | External Data Representation
Rpc | Common types and exceptions
Rpc_program | RPC programs
Rpc_client | RPC clients
Rpc_simple_client | Synchronous API for RPC clients
Rpc_server | RPC servers
Rpc_auth_sys | Authentication module AUTH_SYS
Rpc_portmapper | Portmapper version 2
Rpc_portmapper_aux |
Rpc_portmapper_clnt |
Rpc_transport | Low-level RPC transporters
Rpc_packer |

### Guides

- `Rpc_intro`: Introduction
- `Rpc_mapping_ref`: RPC Language Mapping Reference

### The `rpc-auth-local` extension

Authentication for local socket connections.

Rpc_auth_local | Return the authentication method `AUTH_LOCAL`.

### The `rpc-auth-dh` extension

This is Diffie-Hellman authentication for OncRPC (also known as "Secure RPC").

Rpc_auth_dh | Diffie-Hellman authentication (AUTH_DH alias AUTH_DES)
Rpc_key_service | Contact the keyserv daemon to encrypt/decrypt data with the common key.
Rpc_time | Get the time of the server (using the RFC 868 netdate protocol)

### The `rpc-xti` extension

System V provides a network API called XTI in addition to the socket API. This library allows it to connect to RPC services that can only be reached over a local XTI connection ("cots" connection).

Rpc_xti_client | Minimal support for TI-RPC over the XTI API

### The `rpc_ssl` extension

This library allows you to tunnel RPC through SSL/TLS.

Rpc_ssl | Securing RPC by SSL

## The `netclient` library

This library includes clients for HTTP, Telnet, and (incomplete) FTP.

Http_client | HTTP 1.1 client
Telnet_client | Telnet client
Ftp_client | FTP client
Ftp_data_endpoint | Senders and receivers for the FTP data connection

## The `equeue` library

`equeue` is a fundamental library for event queues. It is mainly used by a number of other libraries of Ocamlnet to parallelize network code (so-called multiplexing).

Equeue | `Equeue` implements generic event queues.
Unixqueue | This module generalizes the `Unix.select` function.
Unixqueue_mt | This module initializes Unixqueue for multi-threaded programs.
Uq_engines | An engine performs a certain task in an autonomous way.
Uq_socks5 | This module implements a SOCKS version 5 client (see RFC 1928) for use with the `Uq_engines.connector`, `Uq_engines.listener`, and `Uq_engines.datagram_provider` engine factories.

### Guides

- `Equeue_intro`: Introduction to programming with `equeue`

### The `equeue-gtk1` and `equeue-gtk2` extensions

Extensions for `equeue` to integrate the event queue into user interfaces made with lablgtk and lablgtk2

Uq_gtk | Integration with lablgtk/lablgtk2 event systems

### The `equeue-ssl` extension

Extensions for `equeue` to support SSL

Uq_ssl | Asynchronous SSL connections

### The `equeue-tcl` extension

Extension for `equeue` to integrate the event queue into user interfaces made with labltk

Uq_tcl | Integration with the labltk event system

## The `pop` library

This is a simple POP 3 client.

Netpop | This is an interface for the Post Office Protocol - Version 3 (POP3) as specifed by RFC 1939.

## The `smtp` library

This is a simple SMTP client.

Netsmtp | This is an interface for the Simple Mail Tranfer Protocol (SMTP) as specified by RFC 2821.

## The `shell` library

The `shell` library allows you to start external commands. It is integrated into `equeue`.

Shell | Calls external programs, creates pipelines, etc.
Shell_sys | Calls external programs, creates pipelines, etc.
Shell_uq | Run shell commands within Unixqueues
Shell_mt | Multi-threading support

### Guides

- `Shell_intro`: Motivation for `shell`

## The `netshm` library

The `netshm` library manages a shared memory object either as hash table or array. It is designed to be used in multi-processing program architectures.

Netshm | Shared memory for O'Caml programs using multi-processing
Netshm_data | Data representation for shared memory
Netshm_hashtbl | Hash tables in shared memory
Netshm_array | Arrays in shared memory

### Guides

- `Netshm_intro`: Shared Memory for IPC

## The `netsys` library

The `netsys` library contains a number of low-level functions used by other Ocamlnet libraries.

Netsys | Some POSIX system calls missing in the `Unix` module

## Index

Index of types
Index of exceptions
Index of values
Index of class attributes
Index of class methods
Index of classes
Index of class types
Index of modules
Index of module types

## Authors

The Ocamlnet libraries have been initially written by Gerd Stolpmann and Patrick Doane.

Contributions by

- Nicolas George: Netdate
- Eric Stokes: FastCGI support
- Pierre Habouzit: SMTP client
- Christophe Troestler: Revised version of `netcgi`
- Deokhwan Kim: Support for EUC-KR

Sponsorships by

- Baretta s.r.l: Nethttpd
- California State University: SSL support for RPC, Netplex