NOTE:
This project is no longer being maintained: it was developed for my masters thesis, which was completed in early 1997. I still, however, welcome any questions or comments that people may have.

[Home] [ToC] [Up] [Prev] [Next]

iHTML Browser Services

URLs

This module defines the types and functions needed to access a browser's internal networking and URL handling mechanism. This allows the system to take advantage of this functionality that is already built into the browser, and for the browser to regulate the system's network access. These services are typically implemented as part of the browser's glue, and must be implemented for the iHTML system to work.

Types

IHRetrieveCallback

Synopsis

Function called as data becomes available from a URL transaction.

Definition

typedef IHRetrieveRequestP (*IHRetrieveCallback)
     IH_PROTO((IHGlobalInfo* interface,
	       IHRetrieveRequestP request,
	       void* userdata));

Parameters

(IHGlobalInfo*) interface: The document scripting interface that initiated this request.
(IHRetrieveRequestP) request: The actual transaction request
(void*) userdata: Arbitrary user data that was attached to the transaction when it was created.

Return

(IHRetrieveRequestP) The request that was handed to the callback, or NULL if this callback is finished.

See Also

IHRetrieveRequestP, BR_RetrieveURL(),

This is the definition of the function callback that is used to inform the owner of a transaction of data as it becomes available.

IHRetrieveRequestP

Synopsis: Handle on a URL transaction.
Definition: void* (This is an opaque type that is defined by the browser's internal implementation.)
See Also: IHReqStatus, IHRetrieveCallback

An abstract handle on a URL transaction that is currently active in the browser.

IHReqStatus

Synopsis

An enumeration of the possible states a URL transaction can be in.

Definition

typedef enum {
  IHReqFinished    = 0x0001,   /* All data is available */
  IHReqIncomplete  = 0x0002,   /* Not all data has been retrieved. */
  IHReqInteractive = 0x0003    /* This is an interactive connection */
} IHReqStatus;

See Also

IHRetrieveRequestP,

This type is used to represent the current status of a URL transaction. The currently defined values are shown above.

Functions

BR_DerefRetrieveRequest

Synopsis

void
		BR_DerefRetrieveRequest(IHRetrieveRequestP req)

Arguments

(IHRetrieveRequestP) req: Transaction request to remove reference from.

Return

nothing.

See Also

IHRetrieveCallback, IHRetrieveRequestP, BR_RetrieveURL()

Removes a reference from the IHRetrieveRequestP. If this is the last reference on it, it is deallocated. Normally, a request made by BR_RetrieveURL() starts with two references -- one for the callback hook, and one returned immediately to the caller. Both of these functions must dereference it for it to be deallocated.

BR_GetRequestBuffer / BR_SetRequestBuffer

Synopsis

IHBufferP
		BR_GetRequestBuffer(IHRetrieveRequestP req, int
		read)

IHBufferP
		BR_SetRequestBuffer(IHRetrieveRequestP req, IHBufferP
		buffer)

Arguments

(IHRetrieveRequestP) req: Transaction request.
(int) read: Flag: if non-zero, read all available data into the buffer.
(IHBufferP) buffer: New buffer to place in transaction request.

Return

(IHBufferP) The current buffer of URL data.

See Also

IHRetrieveRequestP, IHBufferP, BR_RetrieveURL()

These functions are a higher-level interface for reading data from a URL. BR_GetRequestBuffer() returns the current data buffer; if read is TRUE, all available data will be read into the buffer before it is returned. This function detaches the buffer from the request -- it is now the responsibility of the caller to deallocate it when done.

BR_SetRequestBuffer() sets the current buffer for a request. This puts it under the respondibility of the request to deallocate or otherwise manipulate it; a subsequent call to BR_GetRequestBuffer() will return the given buffer.

Note that when the callback returns, any data that hasn't yet been read from the URL will automatically be appended to the current buffer. (Or a new buffer created, if one doesn't exist.)

These functions will typically be used together to read a URL. When the request callback starts, it can use BR_GetRequestBuffer() to retrieve the available data and examine it; if it wants to save that data for later and start fresh with the next batch, this is all that needs to be done.

For successively collecting data, the previously retrieved buffer (after any desired modifications) may be given back to the request with BR_SetRequestBuffer(). Further data can then be appended to the buffer after subsequent runs through the callback.

BR_GetRequestHeader

Synopsis

const char* =
		BR_GetRequestHeader(IHRetrieveRequestP req, const char*
		name)

Arguments

(IHRetrieveRequestP) req: Active transaction request.
(const char*) name: Name of transaction header to retrieve.

Return

(const char*) The text associated with the requested header.

nothing.

See Also

IHRetrieveRequestP

Returns a string of the value that this transaction request has for the given header. Note that since these headers must be retrieved from the network, they are not immediately available; the program should wait until after its contact to access the transaction's header information.

The available header names are scheme-dependent. For the http: scheme, they are the standard MIME headers, such as Content-type. Note that the trailing ':' is not included in header names.

BR_GetRequestStatus

Synopsis

IHReqStatus =
		BR_GetRequestStatus(IHRetrieveRequestP req)

Arguments

(IHRetrieveRequestP) req: Active transaction request.

Return

(IHReqStatus) The current status of this transaction.

nothing.

See Also

IHRetrieveRequestP, IHReqStatus

Returns the current status of the given URL transaction request.

BR_GetRequestURL

Synopsis

const char* =
		BR_GetRequestURL(IHRetrieveRequestP req)

Arguments

(IHRetrieveRequestP) req: Active transaction request.

Return

(const char*) The ASCII URL this transaction request is for.

nothing.

See Also

IHRetrieveRequestP

Returns a string representing the URL that this transaction request was created to retrieve.

BR_RetrieveURL

Synopsis

IHRetrieveRequestP
		BR_RetrieveURL(IHGlobalInfo* gi, const char* url,
		IHRetrieveCallback callback, void* userdata)

Arguments

(IHGlobalInfo*) gi: Scripting interface that is making the request.
(const char*) url: Name of URL to retrieve. This may be a relative URL, in which case its base is taken from the scripting interface.
(IHRetrieveCallback) callback: Function to call as data becomes available.
(void*) userdata: Arbitrary user data that can be associated with the request.

Return

(IHRetrieveRequestP) The new URL transaction request.

See Also

IHRetrieveCallback, IHRetrieveRequestP

Retrieves the given URL from the network. This function may or may not finish before returning; you must not expect any data to be available until the callback is called, which may not be able to happen until control is eventually returned back the browser's event loop.

The resulting IHRetrieveRequestP is owned both by the caller and the given callback function; both must indicate that they are done with it for it to be deallocated. This is accomplished from the caller by calling BR_DerefRetrieveRequest() on the request returned by this function, and from the callback by returning a NULL result.

The function returns a IHRetrieveRequestP structure, which contains information about this request. If NULL is returned, the request failed.

A special URL scheme of the form "tcp://machine:port" is defined by the iHTML system, and must be implemented by the browser. This opens an interactive TCP/IP socket with the given machine and at the given port number. In this case, the returned IHRetrieveRequest is guaranteed to be interactive; the application may write data through calls to BR_WriteRequestBuffer(), and the IHRetrieveCallback function is called whenever one or more bytes of data come over the network.

BR_WriteRequestBuffer

Synopsis

void
		BR_WriteRequestBuffer(IHRetrieveRequestP req, IHBufferP
		buffer)

Arguments

(IHRetrieveRequestP) req: Transaction request to write data to.
(IHBufferP) buffer: Data to write.

Return

nothing.

See Also

IHRetrieveRequestP, IHBufferP, BR_RetrieveURL()

This function is used for interactive sessions -- which currently only applies to the "tcp:" URL. The data in the given buffer is sent over the network connection defined by the given IHRetrieveRequestP. As soon as this function returns, the buffer is available to the caller for re-use. Note that this function does not block -- the data will probably not be transmitted until after it returns.

[Home] [ToC] [Up] [Prev] [Next]

_________.oo_Q_Q_oo.____________________________________________

Dianne Kyra Hackborn <hackbod@angryredplanet.com>
Last modified: Tue Oct 8 04:01:26 PDT 1996

This web page and all material contained herein is Copyright (c) 1997 Dianne Hackborn, unless otherwise noted. All rights reserved.