NETLIB II

URL

Definition

package netscape.url;
import netscape.jmc.*;
import netscape.types.*;

public abstract class URL {
    public URL(String address) throws Exception {};

    public abstract String GetAddress();
    public abstract void SetAddress(String add) throws Exception;

    public abstract String GetDestinationAddress();
    public abstract void SetDestinationAddress(String dest) throws Exception;

    public abstract String GetIPAddressString();
    public abstract void SetIPAddressString(String string) throws Exception;

    // HTTPMethod is an enumeration that contains the following:
    // Get, Post, Head, Put, Delete, Mkdir, Move, Index, and Other.
    // "Other" is for random HTTP methods, set with SetMethodName.
    // Caling SetMethodName automatically sets the method enum to Other;
    // Don't set the enumeration to Other directly.

    public abstract HTTPMethod GetMethod();
    public abstract void SetMethod(HTTPMethod method) throws Exception;

    public abstract String GetMethodName();
    public abstract void SetMethodName(String string) throws Exception;

    // ServerID: this is the introductory string sent by the server.
    // For HTTP it's the "Server:" header (or NULL if there wasn't one).
    // For things like FTP, NNTP, SMPT, etc. it's the introductory header
    // sent by the server upon connection.  GetIsNetsite returns true
    // if the server id indicates a Netscape (or "Netsite") server.

    public abstract String GetServerID();
    public abstract void SetServerID(String string) throws Exception;
    public abstract boolean GetIsNetsite();

    // This "server status" code is always an HTTP status code, even for
    // other protocols: so if an FTP server says "file not found," this will
    // still be HTTP's "404" code.

    public abstract int GetServerStatus();
    public abstract void SetServerStatus(int status);

    // Some booleans about the resource

    public abstract boolean GetIsDirectory();
    public abstract void SetIsDirectory(boolean isdir);

    public abstract boolean GetIsBinaryStream();
    public abstract void SetIsBinaryStream(boolean is_binary);

    // Headers: HeaderDirection is an enumeration with two values:
    // Incoming and Outgoing.  The sets of headers are distinct.

    // SetHeader with two arguments adds the entire string as a line.
    public abstract void SetHeader(HeaderDirection which, String line) throws Exception;

    // SetHeader with three arguments adds a line in the form "name: value"
    public abstract void SetHeader(HeaderDirection which, String name, String value) throws Exception;

    // GetHeader with a string argument gets that name's value, or NULL if it doesn't exist.
    public abstract String GetHeader(HeaderDirection which, String name);

    // GetHeader with a numeric argument gets the n'th header, in the order returned.
    // If n is out of range, this returns NULL.
    public abstract String GetHeader(HeaderDirection which, int n);

    // The header count.
    public abstract int GetHeaderCount(HeaderDirection which);

    // Some headers are complex (or hard to parse), and some values are rather common,
    // so they get special-case routines.

    public abstract String GetIncomingContentType();
    public abstract String GetIncomingContentEncoding();
    public abstract String GetIncomingContentName();
    public abstract String GetIncomingCharset();
    public abstract Time GetIncomingExpiration() throws Exception;
    public abstract Time GetIncomingLastModified() throws Exception;
    public abstract Time GetIncomingServerDate() throws Exception;

    public abstract int GetIncomingContentLength();
    public abstract void SetOutgoingContentLength(int length) throws Exception;

    // Deferred until later: attaching outgoing data directly (instead of streaming
    // it out), this includes multiple file posting; caching, which includes forced
    // reload, can-do-byteranges, and other stuff; direct authentication header
    // support (but you can use the general header routiens); security; history.
}

Interface Methods

• URL

This creation method instantiates a new URL class object, with the argument being used for the address, and everything else being null or zero. The argument is duplicated internally.

The C signature of this method is:

URL *URLFactory_Create(JMCException **e, const char *address);

Note that, as this is a creation method, the exception comes first.

• GetAddress

This method returns a pointer to the URL address string. This pointer points to internal data, so if you want to hang onto it, duplicate it.

The C signature of this method is:

const char *URL_GetAddress(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetAddress

This method sets the address of a URL. The argument is duplicated internally, and any space previously allocated internally is automatically freed. Passing a null pointer is not legal, and will raise an exception.

The C signature of this method is:

void URL_SetAddress(URL *self, const char *address, JMCException **e);
• GetDestinationAddress

Some URL operations, e.g., RENAME, have a destination address as well. This method gets that address; it returns null if there isn't one. This pointer points to internal data, so if you want to hang onto it, duplicate it.

The C signature of this method is:

const char *URL_GetDestinationAddress(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetDestinationAddress

This method sets the destination address. The argument is duplicated internally, and any space previously allocated internally is automatically freed. Passing a null pointer is legal, and will clear the address.

The C signature of this method is:

void URL_SetDestinationAddress(URL *self, const char *destination, JMCException **e);
• GetIPAddressString

The IP Address String is an ascii string containing the network address(es) of the host to which the address points. This data is required for some security checking. This method gets that string, or a null if there isn't one. This pointer points to internal data, so if you want to hang onto it, duplicate it.

The C signature of this method is:

const char *URL_GetIPAddressString(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetIPAddressString

This method sets the IP Address String. The argument is duplicated internally, and any space previously allocated internally is automatically freed. Passing a null pointer is legal, and will clear the string.

The C signature of this method is:

void URL_SetIPAddressString(URL *self, const char *addresses, JMCException **e);
• GetMethod

This method gets the ``HTTP method'' to be performed, i.e., GET, PUT, etc. The return value is defined in URL.h.

The C signature of this method is:

URL_HTTPMethod URL_GetMethod(URL *self, JMCException **e);

If the return value indicates an "Other" method, the name of the method may be obtained with URL_GetMethodName below.

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetMethod

This method sets the ``HTTP method'' to be performed, i.e., GET, PUT, etc. The argument value is defined in URL.h.

The C signature of this method is:

void URL_SetMethod(URL *self, URL_HTTPMethod method, JMCException **e);

The method may not indicate an "Other" method; attempting that will return an exception. Set an other method with URL_SetMethodName, below.

• GetMethodName

This method returns the text name of a method, i.e, "GET," "PUT," etc. If an "Other" method has been specified with URL_SetMethodName below, that name is returned. The return value points to internal storage; if you want to hang onto the value, duplicate the string.

The C signature of this method is:

const char *URL_GetMethodName(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetMethodName

This method sets the text name of the method to be used in the URL connection. For example, an HTTP proxy that can pass arbitrary new HTTP actions might use this to blindly replicate an action that it doesn't really understand. This method has a side effect of setting the method, as returned by URL_GetMethod above, to "other." If the string passed in is a known method, e.g., "GET," the method will still be set to "other"! The value passed in will be duplicated internally.

The C signature of this method is:

void URL_SetMethodName(URL *self, const char *name, JMCException **e);
• GetServerID

This method returns the identification string sent by the server. HTTP servers send this data in a Server: header; FTP, NNTP, SMTP, and many other servers send it as the introductory message send upon connection. The return value points to internal storage; if you want to hang onto the value, duplicate the string.

The C signature of this method is:

const char *URL_GetServerID(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetServerID

This method sets the server ID. The strings passed in will be duplicated internally.

The C signature of this method is:

void URL_SetServerID(URL *self, const char *id, JMCException **e);
• GetIsNetsite

This method examines the server id string as returned by URL_GetServerID above, and returns true if the server is a Netscape product.

The C signature of this method is:

jbool URL_GetIsNetsite(URL *self, JMCException **e);
• GetServerStatus

This method returns a number indicating the server status, in response to a connection. The number is always in the HTTP server-response space: the HTTP protocol module assigns the actual HTTP server's response code here, the other protocol modules translate their servers' responses into HTTP-like numbers.

The C signature of this method is:

jint URL_GetServerStatus(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetServerStatus

This method sets the server status code.

The C signature of this method is:

void URL_SetFileAsPostData(URL *self, jint status, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIsDirectory

This method returns a boolean value, which will be true if the object is identifiably a directory or index of some kind.

The C signature of this method is:

jbool URL_GetIsDirectory(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetIsDirectory

This method sets the "is directory" flag for the object.

The C signature of this method is:

void URL_SetIsDirectory(URL *self, jbool isdir, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIsBinaryStream

This method returns a boolean value, which will be true if the object is identifiably a "binary" object which should not be directly presented to the user.

The C signature of this methods is:

jbool URL_GetIsBinaryStream(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetIsBinaryStream

This method sets the "is binary steram" flag for the object.

The C signature of this method is:

void URL_AddPostHeaders(URL *self, const char *string, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• SetHeader

This method adds the provided string to the specified set of headers. The which argument is of type URL_HeaderDirection, defined in URL.h, and may take the values URL_IncomingHeader or URL_OutgoingHeader. Incoming headers are the headers sent by the server for client consumption; outgoing headers are set by the client for use by the server. The string is added as is, and must conform to the form expected by the server (usually, "Keyword: value"). The string is duplicated internally.

The C signature of this method is:

void URL_SetHeader(URL *self, URL_HeaderDirection which, const char *header, JMCException **e);
• SetHeader_1

This method adds a header, of the form "keyword: value," to the specified header set. The which argument is of type URL_HeaderDirection, defined in URL.h, and may take the values URL_IncomingHeader or URL_OutgoingHeader. Incoming headers are the headers sent by the server for client consumption; outgoing headers are set by the client for use by the server. The strings are combined into a header, which is duplicated internally.

The C signature of this method is:

void URL_SetHeader_1(URL *self, URL_HeaderDirection which, const char *keyword, const char *value, JMCException **e);
• GetHeader

This method gets the value of a named header from the specified header set. The which argument is of type URL_HeaderDirection, defined in URL.h, and may take the values URL_IncomingHeader or URL_OutgoingHeader. Incoming headers are the headers sent by the server for client consumption; outgoing headers are set by the client for use by the server. The return value points to internal storage; if you want to hang onto the string, duplicate it. Note that this method returns a pointer to the value of a typical colon-separated header, i.e., calling URL_GetHeader(url, "Content-Type", &e) might return "text/html." The header keyword parameter is case-insensitive, and should not have a trailing colon. The return value will be NULL if there is no matching header.

The C signature of this method is:

const char *URL_GetHeader(URL *self, URL_HeaderDirection which, const char *keyword, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetHeader_1

This method returns the nth header from the specified header set, in the order in which the headers were set. The which argument is of type URL_HeaderDirection, defined in URL.h, and may take the values URL_IncomingHeader or URL_OutgoingHeader. Incoming headers are the headers sent by the server for client consumption; outgoing headers are set by the client for use by the server. The return value points to internal storage; if you want to hang onto the string, duplicate it. Note that this method returns a pointer to the entire header, keyword and value, exactly as it was set. The return value will be NULL if the index number is out of range. The index starts with 1.

The C signature of this method is:

const char *URL_GetHeader_1(URL *self, URL_HeaderDirection which, jint n, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetHeaderCount

This method returns the number of headers in the specified set. he which argument is of type URL_HeaderDirection, defined in URL.h, and may take the values URL_IncomingHeader or URL_OutgoingHeader. Incoming headers are the headers sent by the server for client consumption; outgoing headers are set by the client for use by the server.

The C signature of this method is:

jint URL_GetHeaderCount(URL *self, URL_HeaderDirection which, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIncomingContentType

This convenience method returns the content type as specified in the incoming Content-Type header. The return value points to internal storage; if you want to hang onto the string, duplicate it. The return value will be NULL if no content type has been specified in the incoming headers.

The C signature of this method is:

const char *URL_GetIncomingContentType(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIncomingContentEncoding

This convenience method returns the content encoding as specified in the incoming headers. The return value points to internal storage; if you want to hang onto the string, duplicate it. The return value will be NULL if no content encoding has been specified in the incoming headers.

The C signature of this method is:

const char *URL_GetIncomingContentEncoding(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIncomingContentName

This convenience method returns the content name as specified in the incoming headers, or (if it's not specified there), as guessed from the URL address. The return value will be NULL if a content name cannot be obtained.

The C signature of this method is:

const char *URL_GetIncomingContentName(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIncomingCharset

This convenience method returns the character set as specified in the incoming headers. The return value will be NULL if a character set was not specified in the incoming headers.

The C signature of this method is:

const char *URL_GetIncomingCharset(URL *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• GetIncomingExpiration

This convenience method returns the expiration date as specified by the incoming Expires header. If no appropriate header has been set, an exception will be "thrown," and the return value will be indeterminate.

The C signature of this method is:

PRTime URL_GetIncomingExpiration(URL *self, JMCException **e);
• GetIncomingLastModified

This convenience method returns the last-modified date as specified by the incoming headers. If no appropriate header has been set, an exception will be "thrown," and the return value will be indeterminate.

The C signature of this method is:

PRTime URL_GetIncomingLastModified(URL *self, JMCException **e);
• GetIncomingServerDate

This convenience method returns the server's current date, as specifeid by the incoming headers. If no appropriate header has been set, an exception will be "thrown," and the return value will be indeterminate.

The C signature of this method is:

PRTime URL_GetIncomingServerDate(URL *self, JMCException **e);
• GetIncomingContentLength

This convenience method returns the object's content length, as specified by the incoming headers. If no appropriate header has been set, an exception will be "thrown," and the return value will be indeterminate.

The C signature of this method is:

jint URL_GetIncomingContentLength(URL *self, JMCException **e);
• SetOutgoingContentLength

This convenience method sets the outgoing "Content-Length" header to the specified value.

The C signature of this method is:

void *URL_GetContentType(URL *self, jint length, JMCException **e);

Inherited Methods

C interface

#include "URL.h"

URL *URLFactory_Create(JMCException **e, const char *address);
const char *URL_GetAddress(URL *self, JMCException **e);
void URL_SetAddress(URL *self, const char *address, JMCException **e);
const char *URL_GetDestinationAddress(URL *self, JMCException **e);
void URL_SetDestinationAddress(URL *self, const char *destination, JMCException **e);
const char *URL_GetIPAddressString(URL *self, JMCException **e);
void URL_SetIPAddressString(URL *self, const char *addresses, JMCException **e);
URL_HTTPMethod URL_GetMethod(URL *self, JMCException **e);
void URL_SetMethod(URL *self, URL_HTTPMethod method, JMCException **e);
const char *URL_GetMethodName(URL *self, JMCException **e);
void URL_SetMethodName(URL *self, const char *name, JMCException **e);
const char *URL_GetServerID(URL *self, JMCException **e);
void URL_SetServerID(URL *self, const char *id, JMCException **e);
jbool URL_GetIsNetsite(URL *self, JMCException **e);
jint URL_GetServerStatus(URL *self, JMCException **e);
void URL_SetServerStatus(URL *self, jint status, JMCException **e);
jbool URL_GetIsDirectory(URL *self, JMCException **e);
void URL_SetIsDirectory(URL *self, jbool isdir, JMCException **e);
jbool URL_GetIsBinaryStream(URL *self, JMCException **e);
void URL_SetIsBinaryStream(URL *self, jbool isbinary, JMCException **e);
void URL_SetHeader(URL *self, URL_HeaderDirection which, const char *header, JMCException **e);
void URL_SetHeader_1(URL *self, URL_HeaderDirection which, const char *keyword, const char *value, JMCException **e);
const char *URL_GetHeader(URL *self, URL_HeaderDirection which, const char *keyword, JMCException **e);
const char *URL_GetHeader_1(URL *self, URL_HeaderDirection which, jint n, JMCException **e);
jint URL_GetHeaderCount(URL *self, URL_HeaderDirection which, JMCException **e);
const char *URL_GetIncomingContentType(URL *self, JMCException **e);
const char *URL_GetIncomingContentEncoding(URL *self, JMCException **e);
const char *URL_GetIncomingContentName(URL *self, JMCException **e);
const char *URL_GetIncomingCharset(URL *self, JMCException **e);
PRTime URL_GetIncomingExpiration(URL *self, JMCException **e);
PRTime URL_GetIncomingLastModified(URL *self, JMCException **e);
PRTime URL_GetIncomingServerDate(URL *self, JMCException **e);
jint URL_GetIncomingContentLength(URL *self, JMCException **e);
void URL_SetOutgoingContentLength(URL *self, jint length, JMCException **e);

/* methods inherited from base JMC object interface */
void *URL_getInterface(URL *self, JMCInterfaceID id, JMCException **e);
void URL_addRef(URL *self, JMCException **e);
void URL_release(URL *self, JMCException **e);
jint URL_hashCode(URL *self, JMCException **e);
void *URL_clone(URL *self, JMCException **e);
const char *URL_toString(URL *self, JMCException **e);
void URL_finalize(URL *self, JMCException **e);