Chapter 13

Status Methods

CONTENTS

• Introduction
• Giving Status
  • Your Own Progress Indicator
• Netscape's User-Agent
  • What the Heck Is Mozilla?
• API Quick Reference
  • NPN_Status
  • NPN_UserAgent
• Conclusion
• What's Next?

Introduction

With the sometimes lengthy delays you can encounter when using today's World Wide Web, it's important to continuously update the user with the status of the current operation. Netscape Navigator accomplishes this with a line of text at the bottom of the browser. Everything from URLs to transfer status is displayed in this line. Your plug-in also has the opportunity to give status in this area with the NPN_Status method.

A Web browser's User-Agent field is sent to an HTTP server during client server communications. This field is very important for generating universal statistics on browser usage. A plug-in can access this information with the NPN_UserAgent method.

This chapter covers the following APIs:

NPN_Status
NPN_UserAgent

Giving Status

As an avid Netscape Navigator user, it would be hard for you not to notice the status line on the bottom of the user interface. This single line of text gives the user all kinds of information, from URLs to progress reports (see Figure 13.1).

Figure 13.1 : Nescape's status line showing a URL during a Yaboo search request.

Your plug-in is given the capability to print status in the same area as the Navigator with the NPN_Status API. This API is very simple to use. Just provide a character buffer with whatever information you would like to display and Navigator will show it to the user.

Your Own Progress Indicator

One of the coolest things that you can put in the status line is a file progress indicator. The parameters stream->end, offset, and len are provided during NPP_Write and can be used to create your own progress indicator based on data streaming to your plug-in. Here is a Windows sample method to accomplish this:

//
// ShowProgress
//
void CWorker::ShowProgress (NPP instance,
    uint32 FileSize,
    int32 Offset,
    int32 len)
{
    DWORD dwCurTick = GetTickCount ();

    if (dwLastTickCount)
    {
        float BytesPerSecond =  (float)len / ((float)(dwCurTick - this->dwLastTi
ÂckCount) / (float)1000.0);

        int SecsRemain = (int)((FileSize - Offset) / BytesPerSecond);

        int MinutesRemain = SecsRemain / 60;

        SecsRemain -= MinutesRemain * 60;

        int PercentComplete = (int)((float)Offset / (float)FileSize * 100);

        CString OutPut;

        OutPut.Format ("%d%% of %dK (at%8.0f bps, %02d:%02d remaining)",
            PercentComplete,
            FileSize / 1024,
            BytesPerSecond * 8,
            MinutesRemain,
            SecsRemain);

        NPN_Status (instance, OutPut.GetBuffer(OutPut.GetLength()));
    }

    // Dont forget to zero out dwLastTickCount after each destroy stream

    this->dwLastTickCount = dwCurTick;

}

This code produces a status line very similar to the one Navigator shows during its file progress. The only difference is that this sample displays file progress in bits per second (bps) rather than Navigator's traditional kilobytes per second (kbps). Using bps provides a nice ratio because it relates directly to the speed of the user's modem.

If you are not developing for Windows, simply replace GetTickCount() with your operating system's equivalent API. Don't forget to zero out dwLastTickCount during initialization and when the stream is destroyed!

Calling the progress method is a simple matter of adding the following line (or your equivalent) to NPP_Write:

data->pWorker->ShowProgress (instance, stream->end, offset, len);

Netscape's User-Agent

When Web browsers communicate with an HTTP server, a User-Agent field is included with most requests. The User-Agent field tells the HTTP server the name of the agent software, its version, and its operating system. This information is very useful for generating statistics on browser usage.

Figure 13.2 : The Browser Watch home page.

One of the most frequently used HTTP requests is GET. As you learned from previous chapters, NPN_GetURL can be used by a plug-in to generate a GET request. The request that the Navigator sends to the server might look something like this:

GET / HTTP/1.0
Connection: Keep-Alive
User-Agent: Mozilla/3.0B2 (Win95; I)
Host: www.browserwatch.com
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*

In this case, the User-Agent is Mozilla/3.0B2 (Win95; I).

What the Heck Is Mozilla?

Mozilla is Netscape's mascot. He is a fire-breathing Godzilla-like creature who appears now and then on Netscape's home page. It's rumored that this mascot was chosen to stomp out the competition. That would be NSCA Mosaic at the time.

API Quick Reference

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

NPN_Status

NPN_UserAgent

Conclusion

A plug-in can give the browser user status through the traditional status line provided by the Navigator. The user should be made aware of any lengthy operations and, when possible, the percentage complete of the current operation should be given.

The User-Agent field provides a plug-in with the best source of information regarding the correct version of the browser hosting your plug-in.

What's Next?

The next chapter is a collection of APIs that didn't really fit into any of the previous chapters. The NPP_SetWindow, NPP_Print, and NPP_HandleEvent APIs are covered in Chapter 14.