Chapter 10

Stream Creation and Destruction

CONTENTS

• Introduction
• New Streams and Their Parameters
  • Stream Type
  • Stream Instance Structure
  • Seeking for Seek
  • Processing by Stream or by File
• Life of a Stream Ends
  • Some Familiar Structures
• Creating Your Own Streams
• NPN_GetURL and NPN_PostURL
  • HTTP GET
  • HTTP POST
  • Emulate the Form with NPN_PostURL
  • Targeting Windows with NPN_GetURL and NPN_PostURL
• API Quick Reference
  • NPP_NewStream
  • NPP_DestroyStream
  • NPN_NewStream
  • NPN_DestroyStream
  • NPN_GetURL
  • NPN_PostURL
• New Navigator 3.0 Plug-In APIs
  • NPN_GetURLNotify
  • NPN_PostURLNotify
  • NPP_URLNotify
• Conclusion
• What's Next?

Introduction

This chapter introduces the plug-in APIs that are responsible for creating and destroying streams both directly and indirectly. You will learn how to get valuable information from a new stream, such as the MIME type, last modification date, and whether it supports seeking with byte range requests. Stream instance structures are reviewed along with stream type return values.

Additionally, the APIs NPN_GetURL and NPN_PostURL, in addition to the new Navigator 3.0 APIs NPN_GetURLNotify, NPN_PostURLNotify, and NPP_URLNotify, are introduced with many code examples. You will learn how these APIs are also responsible for the creation of new data streams.

This chapter also introduces you to the following APIs:

NPP_NewStream
NPP_DestroyStream
NPN_NewStream
NPN_DestroyStream
NPN_GetURL
NPN_PostURL
NPN_GetURLNotify
NPN_PostURLNotify
NPP_URLNotify

The end of the chapter contains a quick reference with code examples for each of these APIs.

New Streams and Their Parameters

When the Navigator encounters a URL with a MIME type of your plug-in's registration, a stream is created to send the URL's data to your streaming routines. You are notified of a new stream with a call to your plug-in's API NPP_NewStream.

NPP_NewStream provides your code module with the parameters type, stream, seekable, and stype. These values contain important information concerning your stream.

Stream Type

The type value is a pointer to a buffer containing the MIME type that caused the creation of the stream. These can be one of the types that your plug-in registered with Netscape or a totally unrelated MIME type, perhaps originating from a call to NPN_GetURL. This type might not match the MIME type sent to a new plug-in instance via the NPP_New call.

Stream Instance Structure

A stream instance structure is passed to you with the stream parameter. This is a pointer to an NPStream structure currently defined as follows:

typedef struct _NPStream
{
    void*       pdata;
    void*       ndata;
    const char* url;
    uint32      end;
    uint32      lastmodified;
} NPStream;

Within this structure, you notice some familiar friends: pdata and ndata. ndata points to the Navigator's instance data, and pdata is an extra pointer for your plug-in's use in streaming. For example, you might want to allocate an object and attach it to pdata so that your plug-in can easily manage a given stream. This technique is especially useful in tracking multiple streams within a plug-in.

stream->pdata = new MyStreamTrackingObject;

Also note url, end, and lastmodified. The url member tells you which URL is responsible for the creation of this stream. This can be handy for requesting more URLs via NPN_GetURL. The end member gives you the size of the requested stream. The lastmodified member indicates when the file associated with the URL was last modified.

Seeking for Seek

The seekable parameter of NPP_NewStream indicates whether the stream supports seeks or byte range requests. Byte range requests are performed through the use of NPN_RequestRead, which is documented in later chapters. Unfortunately, requesting a random block of a file is very new to the world of Web servers. At the time of this writing, most servers do not support it. You can, however, seek within a file that is already on the local system. Additionally, a stream is seekable if it has previously been cached on the local system.

Processing by Stream or by File

Speaking of local files, you might be interested in the stype parameter. This is a pointer to a value that is filled with the requested mode of streaming. The values are as follows:

• NP_NORMAL: This value is the default and does not need to be set. NP_NORMAL implies that your plug-in will process the data in a streaming manner or as it comes to you.
• NP_SEEK: This value asks for seeking capabilities as discussed previously.
• NP_ASFILE: This value tells the Navigator that you want to wait for the whole file to be completely downloaded before beginning processing. This type corresponds with the NPP_StreamAsFile API, which is called when the file is ready. The file is temporarily stored within Netscape's file caching mechanism for processing.
• NP_ASFILE streams display all of the behavior of NP_NORMAL streams such as calls to NPP_WriteReady and NPP_Write. The difference is that they also call NPP_StreamAsFile just before NPP_DestroyStream.
• NP_ASFILEONLY: This is a new type for the Navigator 3.0 plug-in API. This type is much more efficient than NP_ASFILE because it prevents a file from streaming if it is already on the system's local drive, which allows your plug-in to access the file with normal system-level file I/O instead of using Navigator's built-in streaming mechanism.

Life of a Stream Ends

When a stream is complete or interrupted, Netscape makes a call to your NPP_DestroyStream API. Although it is called in streams of type NP_ASFILE, this API is really only relevant to plug-ins that process data in a streaming fashion. Plug-ins that are file based are notified to begin processing with a call to NPP_StreamAsFile.

If you are writing a streaming-based plug-in, you should pay close attention to NPP_DestroyStream. For example, if your plug-in is processing data buffers as they come across the net and a user stops the transfer, the plug-in needs to know that no more data is coming. File-based plug-ins don't care because they don't begin processing until the file is fully downloaded.

Some Familiar Structures

NPP_DestroyStream contains three parameters: instance, stream, and reason. The instance structure is the same as with most APIs. The stream structure is identical to when it left NPP_NewStream. The reason parameter tells you why the stream is being destroyed.

The following are possible reasons for stream destruction:

NPRES_NETWORK_ERR
NPRES_USER_BREAK
NPRES_DONE

NPRES_NETWORK_ERR, as the name says, is a network error. This could be caused by someone picking up a phone during a modem connection. NPRES_USER_BREAK is caused by the user aborting the streaming process by pressing the Stop button, going to another link, or even ending the application. NPRES_DONE indicates that the file has been fully transferred.

Creating Your Own Streams

With the release of Netscape's Navigator 3.0 plug-in API comes the methods NPN_NewStream, NPN_DestroyStream, and NPN_Write. These methods were present in the 2.0 API release, but they did not work at that time. You can use these APIs to create and manage a data stream from your plug-in to the Navigator. One good application would be using a plug-in as a filter.

Chapter 19, "The CPU Monitor Plug-In," gives an example of a plug-in running a CGI program through the use of NPN_GetURL. This program runs a UNIX command called vmstat and gets the results of the command from a Navigator-created data stream. The plug-in then displays this data with a bar graph within the plug-in's window. You can use part of this technique to make your plug-in act as a filter for the Navigator.

For the sake of this discussion, assume that your boss wants to view UNIX-style man pages within Netscape's Web Broswer. Your plug-in can run a CGI program as in the CPU Monitor plug-in that runs man with a given command. After Navigator streams back the results of the CGI program, your plug-in can buffer this data and create a stream to Netscape's Navigator. The plug-in acts as a filter because it can take raw man text and convert it to formatted HTML for display by the Navigator. The following code shows some highlights for using this technique:

//
// Send HTML formatted data to the Navigator
//

.
.
.

// Allocate and clear an NPStream structure

NPStream stream;
memset (&stream, 0, sizeof(NPStream));

// Create a new stream of MIME type "text/html"
// and target a blank web page

NPError rc = NPN_NewStream (instance, "text/html", "_blank", &stream);

// Write the previously formatted HTML data to the Navigator

bytesWritten = NPN_Write (instance, &stream, htmlLen, htmlBuffer);

.
.
.

// Destroy the stream when finished

rc = NPN_DestroyStream (instance, &stream, NP_RESDONE);

At the time of this writing, Navigator 3.0 is still in beta and the APIs as shown in the preceding code block are not yet fully functional. Because of this, you won't find any working code examples of a plug-in acting as a filter in this book.

NPN_GetURL and NPN_PostURL

Both NPN_GetURL and NPN_PostURL are resolved to HTTP server methods by the Navigator. Server methods indicate what to do with the object referenced by the given URL. As the names imply, NPN_GetURL resolves to a GET and NPN_PostURL resolves to a POST. (If you want to read up on other HTTP methods, a good place to start is The World Wide Web Consortium at http://www.w3.org.)

The main difference between GET and POST is that GET is used mostly for requesting URL objects, while POST is the preferred method of sending data to a server. That doesn't mean GET is never used to send data. In fact, many HTML programs embed data within the URL in the form of name=value pairs. For example, a Yahoo search for the string "Netscape" yields the following:

http://search.yahoo.com/bin/search?p=Netscape

Although GET is restricted to inserting data directly in the URL string, POST is more advanced and appends data after the POST header.

HTTP GET

The GET server method is used for most requests for URLs. For example, if you type http://www.yahoo.com in your Web browser, the browser sends the following GET request to the HTTP server:

GET / HTTP/1.0
If-Modified-Since: Monday, 25-Mar-96 23:48:32 GMT; length=5683
Connection: Keep-Alive
User-Agent: Mozilla/2.01 (Win95; I)
Host: www.yahoo.com
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*

Although the specifics of this GET header are relevant to HTTP syntax and beyond the scope of this book, you can get a good idea of what the browser is looking for by reading the text.

After the GET request is sent, the browser waits patiently for word from the server. In the case of Yahoo, you end up with the following:

HTTP/1.0 200 OK
Last-Modified: Wed, 27 Mar 1996 09:33:06 GMT
Content-Type: text/html
Content-Length: 5688

<HTML>
.
.
.
</HTML>

Reading through the text, you can see the last modification date, content type, and content length. The actual HTML code has been removed for the sake of brevity. Within the HTML code are mode URL objects such as graphics, which cause your browser to issue more GET commands.

HTTP POST

The POST HTTP method is the preferred method for sending data to HTTP servers. Send- ing data to a server in this manner requires a server script or program using the Common Gateway Interface (CGI). A CGI program lives in a special directory that is set up by the server administrator. If you don't have access to a server, check out the National Center for Supercomputing Applications (NCSA) Fill-Out Form Support Page, which is currently located at the following address:

http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/fill-out-forms/overview.html

You can test your programming skills using Netscape's NPN_PostURL by emulating one of the NCSA sample forms. For example, take a look at the form shown in Figure 10.1.

Figure 10.1 : An example form that passts data to a CGI program from NCSA.

If you view the HTML source for this example, you see the following simple FORM defined:

<FORM METHOD="POST" ACTION="http://hoohoo.ncsa.uiuc.edu/cgi-bin/post-query">

A single text entry field goes here: <INPUT NAME="entry"> <P>

Note that it has no default value. <P>

To submit the query, press this button: <INPUT TYPE="submit"
VALUE="Submit Query">. <P>

</FORM>

Notice FORM METHOD="POST", which corresponds to an HTTP POST. Also notice ACTION="http://hoohoo.ncsa.uiuc.edu/cgi-bin/post-query". The ACTION points to a URL containing the CGI program to process the FORM.

When a user clicks on the Submit Query button, the following POST is sent to the CGI program post-query:

POST /cgi-bin/post-query HTTP/1.0
Referer: http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/
Âfill-out-forms/example-1.html
Connection: Keep-Alive
User-Agent: Mozilla/2.01 (Win95; I)
Host: hoohoo.ncsa.uiuc.edu
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Content-type: application/x-www-form-urlencoded
Content-length: 13

entry=My+Name

The post-query program is written in C and can be found at the following ftp site:

ftp://ftp.ncsa.uiuc.edu/Web/httpd/Unix/ncsa_httpd/cgi/cgi-src/post-query.c

Take a look at the post-query.c source code from NCSA:

#include <stdio.h>

#define MAX_ENTRIES 10000

typedef struct {
    char *name;
    char *val;
} entry;

char *makeword(char *line, char stop);
char *fmakeword(FILE *f, char stop, int *len);
char x2c(char *what);
void unescape_url(char *url);
void plustospace(char *str);

main(int argc, char *argv[]) {
    entry entries[MAX_ENTRIES];
    register int x,m=0;
    int cl;

    printf("Content-type: text/html%c%c",10,10);

    if(strcmp(getenv("REQUEST_METHOD"),"POST")) {
        printf("This script should be referenced with a METHOD of POST.\n");
        printf("If you don't understand this, see this ");
        printf("<A HREF=\"http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/
        Âfill-out-forms/overview.html\">forms overview</A>.%c",10);
        exit(1);
    }
    if(strcmp(getenv("CONTENT_TYPE"),"application/x-www-form-urlencoded")) {
        printf("This script can only be used to decode form results. \n");
        exit(1);
    }
    cl = atoi(getenv("CONTENT_LENGTH"));

    for(x=0;cl && (!feof(stdin));x++) {
        m=x;
        entries[x].val = fmakeword(stdin,'&',&cl);
        plustospace(entries[x].val);
        unescape_url(entries[x].val);
        entries[x].name = makeword(entries[x].val,'=');
    }

    printf("<H1>Query Results</H1>");
    printf("You submitted the following name/value pairs:<p>%c",10);
    printf("<ul>%c",10);

    for(x=0; x <= m; x++)
        printf("<li> <code>%s = %s</code>%c",entries[x].name,
               entries[x].val,10);
    printf("</ul>%c",10);
}

This CGI program is the back-end of the form shown in Figure 10.1. Here are some things to note:

• A POST method CGI program communicates with the HTTP server through the use of environment variables, standard input, and standard output. Look at the repeated calls to getenv to retrieve REQUEST_METHOD, CONTENT_TYPE, and CONTENT_LENGTH. In the form example shown in Figure 10.1, the REQUEST_METHOD is POST, CONTENT_TYPE is application/x-www-form-urlencoded, and CONTENT_LENGTH is 13.
• After CONTENT_LENGTH is determined, a for loop is entered to parse the given name=value pairs. Note the calls to fmakeword, plustospace, unescape_url, and makeword. The source code for these routines can be found in the file util.c, which is available from the same FTP site as post-query.c.

Emulate the Form with NPN_PostURL

You can produce the same output as the form in Figure 10.1 through the use of NPN_PostURL. Try the following in a test plug-in:

1. Make a buffer with the appropriate content type, content length, and data. You can use a CString to make string building easier. Make sure to include a new line after content type and two new lines after content length:

CString csPost = "Content-type: application/x-www-form-urlencoded\n";
csPost += "Content-length: 13\n\n";
csPost += "Entry=My+Name\n";

1. Use NPN_PostURL to send the data to the URL

// Send data to the server

NPError rc = NPN_PostURL (instance,
    "http://hoohoo.ncsa.uiuc.edu/cgi-bin/post-query",
"_blank",
    csPost.GetLength(),
    csPost.GetBuffer(csPost.GetLength()),
    TRUE);

1. If everything went well, Netscape should connect to the server and display the results shown in Figure 10.2.

Figure 10.2 : NCSA's CGI program responds to a cal from NPN_PostURL.

If, by the time you are reading this book, NCSA's example has gone away, simply find yourself another FORM example that uses the POST method. Or, if you are lucky enough to have access to an HTTP server, just write your own CGI program.

Targeting Windows with NPN_GetURL and NPN_PostURL

Both NPN_GetURL and NPN_PostURL provide a means for targeting windows. Target windows are windows within the Navigator that receive the data stream associated with a given URL. In most cases, you use the value of NULL for your window target. Using NULL ensures that the data stream is written to your plug-in via NPP_Write. Otherwise, you might specify a number of target windows relating to the TARGET tag within your HTML code or use one of the "magic" target window names.

The following are the current magic target windows:

_blank
_new
_self
_current
_parent
_top

Of these, _blank and _new are synonymous and cause the Navigator to create a new unnamed window instance of itself. The targets _self and _current are also synonyms. They cause the link to load in the same window in which the anchor was clicked.

The target _parent loads the link in the immediate FRAMESET parent of the document, and _top makes the link load in the full body of the window.

For more information on frames and magic window names from Netscape, please consult the following addresses:

http://home.netscape.com/assist/net sites/frames.html
http://home.netscape.com/eng/mozilla/2.0/relnotes/demo/targets/html

API Quick Reference

The following sections give in-depth information on the APIs used in this chapter.

NPP_NewStream

NPP_DestroyStream

NPN_NewStream

NPN_DestroyStream

NPN_GetURL

NPN_PostURL

New Navigator 3.0 Plug-In APIs

NPN_GetURLNotify

NPN_PostURLNotify

NPP_URLNotify

Conclusion

This chapter showed you how to create and destroy streams both implicitly and explicitly. Data structures were defined and parameters both to and from the Navigator were covered. Special attention was given to sending data to HTTP servers with NPN_PostURL.

Make sure to take note of the warnings about use of these APIs. Netscape Navigator 2.x has a few bugs and does not support some of the streaming APIs.

What's Next?

Now that you're an expert at creating streams, it's time to move on to reading and writing to them. In the next chapter, you will see how both NPP and NPN type APIs enable you to move data to and from the server. The next chapter covers the APIs NPP_StreamAsFile, NPP_WriteReady, NPP_Write, NPN_RequestRead, and NPN_Write.