Confirm, emeritus
969
edits
Changes
Linkify a bunch of stuff in the Networking section
A '''protocol handler''' is an XPCOM service associated with a particular URI scheme or network protocol. Necko includes protocol handlers for HTTP, FTP, the data: URI scheme, and various others. Extensions can implement protocol handlers of their own.
A protocol handler implements the <code>[https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIProtocolHandler.idl nsIProtocolHandler]</code> API, which serves three primary purposes:
# Providing metadata about the protocol (its security characteristics, whether it requires actual network access, what the corresponding URI scheme is, what TCP port the protocol uses by default).
# Creating URI objects for the protocol's scheme.
# Creating channel objects for the protocol's URI objects
Typically, the built-in I/O service (<code>[https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIIOService2.idl nsIIOService]</code>) is responsible for finding the right protocol handler for URI object creation and channel creation, while a variety of consumers queries protocol metadata. Querying protocol metadata is the recommended way to handle any sort of code that needs to have different behavior for different URI schemes. In particular, unlike whitelists or blacklists, it correctly handles the addition of new protocols.
A service can register itself as a protocol handler by registering for the contract ID <code>"@mozilla.org/network/protocol;1?name=SSSSS"</code> where <code>SSSS</code> is the URI scheme for the protocol (e.g. "http", "ftp", and so forth).
=== URI objects ===
URI objects, which implement the <code>[https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIURI.idl nsIURI]</code> API, are a way of representing URIs and IRIs. Their main advantage over strings is that they do basic syntax checking and canonicalization on the URI string that they're provided with. They also provide various accessors to extract particular parts of the URI and provide URI equality comparisons. URIs that correspond to hierarchical schemes implement the additional <code>[https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIURL.idl nsIURL]</code> interface, which exposes even more accessors for breaking out parts of the URI.
URI objects are typically created by calling the <code>newURI</code> method on the I/O service, or in C++ by calling the <code>NS_NewURI</code> utility function. This makes sure to create the URI object using the right protocol handler, which ensures that the right kind of object is created. Direct creation of URIs via <code>createInstance</code> is reserved for protocol handler implementations.
=== Channels ===
[https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIChannel.idl Channels ] are the Necko representation of a single request/response interaction with a server. A channel is created by calling the <code>newChannel</code> method on the [https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIIOService.idl I/O service], or in C++ by calling the <code>[https://dxr.mozilla.org/mozilla-central/search?q=function%3ANS_NewChannel&case=true NS_NewChannel]</code> utility function. The channel can then be configured as needed, and finally its <code>asyncOpen</code> method can be called. This method takes an <code>[https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsIStreamListener.idl nsIStreamListener]</code> as an argument.
If <code>asyncOpen</code> has returned successfully, the channel guarantees that it will asynchronously call the <code>onStartRequest</code> and <code>onStopRequest</code> methods on its stream listener. This will happen even if there are network errors that prevent Necko from actually performing the requests. Such errors will be reported in the channel's status and in the <code>status</code> argument to <code>onStopRequest</code>.
