hthost.h

www工具包. 这是W3C官方支持的www支撑库. 其中提供通用目的的客户端的WebAPI: complete HTTP/1.1 (with caching, pipelining, PUT, POS

any pending Net objects and return the first of
these Net objects.
*/

extern HTNet * HTHost_nextPendingNet (HTHost * host);

/*

The second checks the list of pending host objects waiting for a socket and
returns the first of these Host objects.
*/

extern HTHost * HTHost_nextPendingHost (void);

/*
(
  Start the Next Pending reqeust
)

Start the next pending request if any. First we look for pending requests
for the same host and then we check for any other pending hosts. If nothing
pending then register a close event handler to have something catching the
socket if the remote server closes the connection, for example due to timeout.
*/

extern BOOL HTHost_launchPending (HTHost * host);

/*
(
  Stop Launch of Pending Requests
)

Controls whether pending requests should be automatically activated. The
default is on, but if turned off then no pending requests are launched.
*/

extern void HTHost_enable_PendingReqLaunch (void);
extern void HTHost_disable_PendingReqLaunch (void);

/*
.
  Persistent Connections
.

We don't want more than (Max open sockets) - 2 connections to be persistent
in order to avoid deadlock. You can set the max number of simultaneous open
connection in the HTNet manager.
(
  Is this host Persistent?
)
*/

extern BOOL HTHost_setPersistent (HTHost * host, BOOL persistent,
                                  HTTransportMode mode);
extern BOOL HTHost_isPersistent (HTHost * host);

/*
(
  Persistent Connection Timeouts
)

If the server doesn't close the connection on us then we close it after a
while so that we don't unnecessarily take up resources (see also how the
timeouts of individual requests can be set).
Libwww provides two mechanisms: an active timeout and a passive timeout.
The former uses libwww timers and is the preferred
mechanism, the latter passively looks at the Host object when a new request
is issued in order to determine whether the existing channel can be reused.
This is primariliy for non-preemptive requests which in general is deprecated.

By default we have an active timeout of 60 secs and a passive timeout of
120 secs (the latter is longer as this is less reliable). Active timeout
s can be accessed using these functions:
*/

extern BOOL HTHost_setActiveTimeout (ms_t timeout);
extern ms_t HTHost_activeTimeout (void);

/*

and passive timeouts can be accessed using these functions
*/

extern time_t HTHost_persistTimeout (void);
extern BOOL HTHost_setPersistTimeout (time_t timeout);

/*

The following two functions are deprecated:
*/

extern void HTHost_setPersistExpires (HTHost * host, time_t expires);
extern time_t HTHost_persistExpires (HTHost * host);

/*
(
  Keeping Track of Number of Reqeusts
)

Another way to detect when a connection is about to close is to count the
number of requests made. For example, the (current) default bevaior by most
Apache servers is to close a TCP connection after 100 requests. I don't quite
think it makes sense to control the close of a connection like this but anyway,
there we go.
*/

extern void HTHost_setReqsPerConnection (HTHost * host, int reqs);
extern int HTHost_reqsPerConnection (HTHost * host);
extern void HTHost_setReqsMade (HTHost * host, int reqs);
extern int HTHost_reqsMade (HTHost * host);

/*
.
  Read and Write Management
.

Which Net object can read and/or write? When doing
pipelining, we essentially serialize requests and therefore we must keep
track of who can read and who can write.
(
  Get the Next Net object for Reading and Writing
)
*/

extern HTNet * HTHost_firstNet     (HTHost * host);
extern HTNet * HTHost_getReadNet  (HTHost * host);
extern HTNet * HTHost_getWriteNet (HTHost * host);

/*
(
  Get input and output Streams for this Host
)
*/

extern HTInputStream * HTHost_getInput (HTHost * host, HTTransport * transport,
				        void * param, int mode);

extern HTOutputStream * HTHost_getOutput (HTHost * host, HTTransport * tp,
					  void * param, int mode);

/*
(
  Reading Data and Keeping Track of how Much
)

Because of the push streams, the streams must keep track of how much data
actually was consumed by that stream.
*/

extern int HTHost_read(HTHost * host, HTNet * net);

extern BOOL HTHost_setConsumed(HTHost * host, size_t bytes);
extern BOOL HTHost_setRemainingRead(HTHost * host, size_t remainaing);
extern size_t HTHost_remainingRead (HTHost * host);

/*
.
  Pipelining Requests
.

When possible, we try to pipeline requests onto the same connection as this
saves a lot of time and leads to much higher throughput.
(
  How many Requests can we Pipeline onto the same Connection?
)

Use these functions to set the max number of requests that can be pipelined
at any one time on a single, persistent connection. The higher the number,
the more we have to recover if the server closes the connection prematurely.
The default is about 50 requests which is enough to fill most links.
*/

extern BOOL HTHost_setMaxPipelinedRequests (int max);
extern int HTHost_maxPipelinedRequests (void);

/*
(
  How many Pending and Outstanding Net objects are there on a Host?
)

You can query how many Het objects (essentially requests) are outstanding
or pending on a host object using these methods:
*/

extern int HTHost_numberOfOutstandingNetObjects (HTHost * host);
extern int HTHost_numberOfPendingNetObjects (HTHost * host);

/*
(
  Pipeline Recovery
)

Pipelines normally run by themselves (requests are issued and responses
recieved). However, it may be necessry to either prematurely abort a pipeline
or to recover a broken pipeline due to communication problems with the server.
In case a pipeline is broken then we have to recover it and start again.
This is handled automatically by the host object, so you do not have to call
this one explicitly.
*/

extern BOOL HTHost_recoverPipe (HTHost * host);
extern BOOL HTHost_doRecover (HTHost * host);

/*
(
  Kill a Pipeline
)

Call this function to terminate all requests (pending as well as active)
registered with a host object. This is typically the function that handles
timeout, abort (user hits the red button, etc). You can also use the
HTNet object kill method which in terms call this
function.
*/
extern BOOL HTHost_killPipe (HTHost * host);

/*
.
  Event Management
.

These functions are used to register and unregister events (read, write,
etc.) so that the host object knows about it.
*/

extern int HTHost_register(HTHost * host, HTNet * net, HTEventType type);
extern int HTHost_unregister(HTHost * host, HTNet * net, HTEventType type);
extern int HTHost_tickleFirstNet(HTHost * host, HTEventType type);

extern SockA * HTHost_getSockAddr(HTHost * host);

/*
(
  Request Timeouts
)

Events can be assigned a timeout which causes the event to be triggered if
the timeout happens before other action is available on the socket. You can
assign a global timeout for all host object using the following methods.
The default is no timeout.
*/

extern int HTHost_eventTimeout (void);
extern void HTHost_setEventTimeout (int millis);

/*
.
  Delayed Flush Timer
.

These methods can control how long we want to wait for a flush on a pipelined
channel. The default is 30ms which is OK in most situations.
*/

extern BOOL HTHost_setWriteDelay (HTHost * host, ms_t delay);
extern ms_t HTHost_writeDelay (HTHost * host);
extern int HTHost_findWriteDelay(HTHost * host, ms_t lastFlushTime, int buffSize);

/*

It is also possible to explicitly require a flush using the following method.
This can also be set directly in the request object
for a single request.
*/

extern int HTHost_forceFlush(HTHost * host);

/*

You can also set the global value so that all new host objects (and
therefore all new requests) will inherit this value instead of setting it
individually.
*/
extern BOOL HTHost_setDefaultWriteDelay (ms_t delay);
extern ms_t HTHost_defaultWriteDelay (void);

/*
.
  Multi homed Host Management
.

We keep track of hosts with multiple IP addresses - socalled multi-homed
hosts. This is used for two things: finding the fastest IP address of
that host and as a backup if one or more of the hosts are down. This is handled
in connection with the DNS manager
*/

extern BOOL HTHost_setHome (HTHost * host, int home);
extern int HTHost_home (HTHost * host);

extern BOOL HTHost_setRetry (HTHost * host, int retry);
extern int HTHost_retry (HTHost * host);
extern BOOL HTHost_decreaseRetry (HTHost * host);

/*
.
  Notify Request that it has become Active
.

A new callback plugged to the activation of a request which allows an application
to know when a request has become active.
*/

typedef int HTHost_ActivateRequestCallback (HTRequest * request);
extern void HTHost_setActivateRequestCallback
		(HTHost_ActivateRequestCallback * cbf);

/*

*/

#endif /* HTHOST_H */

/*

  

  @(#) $Id: HTHost.html,v 2.29 1999/07/07 15:43:28 frystyk Exp $

*/