NETLIB II

NC: the Net Context

These can be seen as a set of callbacks that the caller must provide to the URL Connection. We have grouped these callbacks together as methods in an interface, called the Net Context. This interface provides the per-connection context required for the netlib to work.

We imagine that there will be several types that implement this interface: one for each front-end, perhaps one for each front-end for mail/news windows, a ``null'' context used internally (by, e.g., the image library), and one or more used in server situations. I would guess that there would be one instance per window, but the details of this are up to the callers.

Note that there is no such thing as a Net Context Group. Never was, never will be.

Definition

package netscape.net;

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

public abstract interface NC {
  // popups
  public abstract boolean confirm(TextMessage m) throws Exception;
  public abstract String prompt(TextMessage m, String d) throws Exception;
  public abstract String getPassword(TextMessage m) throws Exception;

  // registerCallback is needed for multithreading
  // public abstract void registerCallback(PREventQueue queue, Callback callback, Object arg) throws Exception;

  // Instructions to the front end to go do something.  Legacy.
  public abstract void doRemoteHost(int url_type, String host, String port, String username) throws Exception;
  public abstract void setRefreshURLTimer(int seconds, URL url) throws Exception;

  // Dynamic observation points
  public abstract void observe(String name, Observer proc, Object addArg) throws Exception;
  public abstract void notify(String name, int message, Object notifyArg) throws Exception;
}

Interface Methods

• There is no creation method. This is an interface. Each type that implements this interface, however, has some sort of creation method or factory type; see the actual implementations for descriptions.
• confirm

This method takes a text message, uses it to prompt the luser in some appropriate way, and returns the yes/no response as a boolean. Note that a server without some way of finding or deriving the answer may choose to throw an exception to abort the operation.

The C signature of this method is:

jbool NC_confirm(NC *self, struct TextMessage a, JMCException **e);
• prompt

This method takes a text message and default response, and prompts the luser. The response is returned as a string.

The C signature of this method is:

const char *NC_prompt(NC *self, struct TextMessage a, const char *b, JMCException **e);
• getPassword

This method also prompts the luser for a response, but the user dialogue does not display the luser's data. Further, there is no default.

The C signature of this method is:

const char *NC_getPassword(NC *self, struct TextMessage a, JMCException **e);
• registerCallback

This method, elided for the moment, will be used if a protocol handler has to create another thread that must interact with the front-end event loop. This method registers with the front end some sort of NSPR event object, and a callback to be called when the event has occurred. The primary need for this was the synchronous/asynchronous netlib gateway, which wrapped the new threaded netlib in the old asynchronous API.

As this method can be troublesome, and as the now-forseen clients of the netlib do not necessarily need the old asynchronous semantics, this method has been elided for now.

• doRemoteHost

This legacy callback is used when a protocol handler wishes to ask the front end to start up a telnet, rlogin, or tn3270 session. The ``url_type'' argument is defined in purl.h. The ``host,'' ``port,'' and ``username'' arguments are strings, the latter of which may contain a password using usual URL syntax.

The C signature of this method is:

void NC_doRemoteHost(NC *self, jint url_type, const char *host, const char *port, const char *username, JMCException **e);
• setRefreshURLTimer

This legacy callback is used when the protocol handler itself wishes to have the front-end refresh (or redirect) the current document to a specific URL after some interval. This is how the HTTP protocol refresh directive is handled.

The C signature of this method is:

void NC_setRefreshURLTimer(NC *self, jint seconds, URL *url, JMCException **e);
• observe

This method is used to register event observers. I would expect that, typically, the front end that creates an object implementing NC will ``pre-register'' several observers for various named events. Perhaps this method is used to do that. However, this method allows any other code that gets ahold of this net context to also register observers.

The C signature of this method is:

void NC_observe(NC *self, const char *name, XP_ObserverProc proc, void *addArg, JMCException **e);
• notify

This method is called by the protocol handlers to notify observers that certain named events have taken place. As this observation/notification system was, by request, based upon the one defined in xp_obs.h, it inherits that system's inherent synchronous semantics.

The C signature of this method is:

void NC_notify(NC *self, const char *name, jint message, void *notifyArg, JMCException **e);

Inherited Methods

C interface

#include "NC.h"

jbool NC_confirm(NC *self, struct TextMessage a, JMCException **e);
const char *NC_prompt(NC *self, struct TextMessage a, const char *b, JMCException **e);
const char *NC_getPassword(NC *self, struct TextMessage a, JMCException **e);
void NC_doRemoteHost(NC *self, jint url_type, const char *host, const char *port, const char *username, JMCException **e);
void NC_setRefreshURLTimer(NC *self, jint seconds, URL *url, JMCException **e);
void NC_observe(NC *self, const char *name, XP_ObserverProc proc, void *addArg, JMCException **e);
void NC_notify(NC *self, const char *name, jint message, void *notifyArg, JMCException **e);

/* methods inherited from base JMC object interface */
void *NC_getInterface(NC *self, JMCInterfaceID id, JMCException **e);
void NC_addRef(NC *self, JMCException **e);
void NC_release(NC *self, JMCException **e);
jint NC_hashCode(NC *self, JMCException **e);
void *NC_clone(NC *self, JMCException **e);
const char *NC_toString(NC *self, JMCException **e);
void NC_finalize(NC *self, JMCException **e);