This document pertains to the Windows Netscape Navigator version 1.1. All information in this document will also remain valid with future revisions of Netscape for compatibility purposes.

OLE (Object Linking and Embedding) Automation is Netscape's preferred mechanism for interprocess communication under all versions of the Windows operating system. Other forms of interprocess communication, such as DDE (Dynamic Data Exchange), are available depending on an applicaiton's specific needs.

This document describes the OLE Automation implementation that Netscape follows. This document assumes that the reader has knowledge on how to implement an OLE Automation application and/or understands OLE Automation concepts and terminology.

A secure newsgroup for the Netscape Navigator for Windows NCAPI is available. If you have any need to discuss Windows NCAPI issues, please post your comments to the newsgroup.

The URL for the newsgroup is snews://secnews.netscape.com/netscape.ncapi.windows.

Netscape automation objects follow a naming convention. Your OLE automation application does not need to follow this convention, but Netscape's convention is listed here for informational purposes. The automation object names are entered in the system registry as Application.Purpose.Version, where:

• Application is Netscape.
• Purpose is a word indicating the general purpose of the automation object.
• Version is the revision number of the automation object. You will need to explicity use the version of the automation object to ensure the properties and methods of the object are consistent with what your application expects.

A type library (.tlb) is shipped with Netscape and resides in the Netscape installation directory along with the Netscape binary. A type library generally increases the speed at which you can implement communication with the Netscape automation objects if you are using a programming environment that utilizies type libraries.

The Netscape automation object names are currently not inserted into the system registry at installation time. A user of Netscape will need to execute the Netscape binary at least once prior to any usage of the Netscape automation objects by other applications.

Netscape.Network.1 provides network access and file retrieval to other applications. In short, an application using this automation object will be able to access network data through the same mechansisms Netscape uses; including the SSL security procotol, proxy support, SOCKS support, cache support, and the numerous Internet protocols which Netscape natively speaks.

The methods and properties of Netscape.Network.1 are:

1. short BytesReady();
   
   Purpose:
   Inform the caller of the number of bytes prepared to be Read.
   Return Value:
   

   • short is the number of bytes currently ready to be read via an invokation of Read.
   Description:
   Use this method to determine how much data can be read in one subsequent call to Read. This method is provided for informational purposes only. It is not advised that applications using this method wait until a particular amount of data becomes available to be read before invoking Read.
2. void Close();
   
   Purpose:
   Disconnect any active connection and reset the Netscape.Network.1 object.
   Description:
   Invoke this member when you are finished with the load initiated by an earlier call to Open. It is necessary to call this member even if a call to Open fails. All state information held by the Netscape.Network.1 object, retrievable by its various methods, will be reset upon an invokation of Close. Invoking Close during a network download will successfully interrupt the download.
3. CString GetContentEncoding();
   
   Purpose:
   Return the MIME encoding of the current load.
   Return Value:
   

   • CString is the encoding of the current data. If this is an empty string, then there is no encoding.
   Description:
   Call this method only after a successful invokation of Open. The return value of this method can be used to determine what type of decoder will be needed to use the data being retrieved by a load.
4. long GetContentLength();
   
   Purpose:
   Return the content length (total amount of bytes) of the current load.
   Return Value:
   

   • long is the content length. If the value reported is less than or equal to 0, then there was no content length reported by the server.
   Description:
   Use this method only after a successful invokation of Open. The content length is valid only from servers which report an accurate content length; there is no guarantee of the validity. The method is provided for informational purposes only as the value can not be guaranteed by Netscape.
5. CString GetContentType();
   
   Purpose:
   Return the MIME type of the current load.
   Return Value:
   

   • CString is the MIME type of the current load. If this is an empty string, then the content type is unknown.
   Description:
   Call this method only after a successful invokation of Open. The return value of this method can be used to determine what actions to take upon the type of data being received.
6. CString GetErrorMessage();
   
   Purpose:
   Provide the caller with the Netscape internally generated error message.
   Return Value:
   

   • CString is the error message generated by Netscape.
   Description:
   Use this method only when an invokation of GetStatus informs you that an error message is available and if you would like to use the Netscape error message. In no way does Netscape guarantee that these error messages will remain consistant across different versions of Netscape. It is ill advised to compare the string reported by Netscape to any previously known error messages.
7. CString GetExpires();
   
   Purpose:
   Return when the data retrieved by this load is no longer considered valid.
   Return Value:
   

   • CString is a string containing the time and date at which the content expires. If this is an empty string, then no expires date has been specified.
   Description:
   Call this method only after a successful invokation of Open. The return value of this method is generated with the ctime routine.
8. BOOL GetFlagFancyFTP();
   
   Purpose:
   Return wether or not FTP output will contain listing information such as file size, file type, etc.
   Return Value:
   

   • BOOL is TRUE if FTP file listings will contain fancy information. FALSE if only the files will be listed with no extra information.
9. BOOL GetFlagFancyNews();
   
   Purpose:
   Return wether or not Newsgroup listings will contain only newsgroups with an informative description.
   Return Value:
   

   • BOOL is TRUE if Netscape will only list newsgroups that also have descriptions. FALSE if Netscape will list all newsgroups.
10. BOOL GetFlagShowAllNews();
    
    Purpose:
    Return wether or not all news articles will be listed.
    Return Value:
    

    • BOOL is TRUE if all news articles will be listed when loading a URL of protocol type news. FALSE if only unread articles will be shown.
11. CString GetLastModified();
    
    Purpose:
    Return when the data retrived by this load was last modified.
    Return Value:
    

    • CString is a string containing the time and date at which the content was last modified. If this in an empty string, then no last modified date has been specified.
    Description:
    Call this method only after a successful invokation of Open. The return value of this method is generated with the ctime routine.
12. CString GetPassword();
    
    Purpose:
    Determine the currently set password.
    Return Value:
    

    • CString is the password set by a previous call to SetPassword. If this is an empty string, then no password has been set.
13. short GetServerStatus();
    
    Purpose:
    Determine the error status reported by the server.
    Return Value:
    

    • short is the error value returned by the server.
    Description:
    Use this method only if GetStatus informs you that the server reported an error. Server error values in general are protocol (http, gopher, ftp, etc) specific. If you plan on using the server error value to handle exceptions in your application, you will need to know what server error codes are appropriate for each protocol.
14. long GetStatus();
    
    Purpose:
    Query the status of the current load.
    Return Value:
    

    • long holds a set of masks, any of which may be active at a particular call to GetStatus. The available masks and their descriptions are:
      • 0x0000 indicates a normal status, no exceptions.
      • 0x0001 indicates that the user name was requested.
      • 0x0002 indicates that the user password was requested.
      • 0x0100 indicates that Netscape is currently busy; attempt the operation again.
      • 0x0200 indicates that the server reported an error; use GetServerStatus if more information is required.
      • 0x0400 indicates an internal load error and the server was never contacted.
      • 0x0800 informs you that Netscape has suggested an error message; use the method GetErrorMessage if desired.
    Description:
    This method's return value only has meaning after invoking the method Open and before invoking the method Close. When the username or password has been requested by the server, it does not indicate an error condition. Rather, it informs you that if you have not provided a username via SetUsername or a password via SetPassword that the load may fail; the conditions of which can be determined via an invokation of GetServerStatus.
15. CString GetUsername();
    
    Purpose:
    Determine the currently set username.
    Return Value:
    

    • CString is the username set by a previous call to SetUsername. If this is an empty string, then no username has been set.
16. BOOL IsFinished();
    
    Purpose:
    Determine if a load is complete.
    Return Value:
    

    • BOOL is TRUE if no more data remains to be read from the current load. FALSE if the load is not yet complete.
    Description:
    Call this method only after a successful invokation of Open. The return value of TRUE in this mehtod directly correlates with a return value of -1 from Read.
17. BOOL Open(LPCTSTR pURL, short iMethod, LPCTSTR pPostData, long lPostDataSize, LPCTSTR pPostHeaders);
    
    Purpose:
    Initiates the retrieval of a URL from the network.
    Arguments:
    

    • pURL is the URL to attempt to load.
    • iMethod is method in which to retrieve the URL. Normally, you will want to specify a value of 0x0. Possible values are:
      0x0 GET
      0x1 POST
      0x3 HEAD
    • pPostData is the data to post to the server specified in pURL. This argument is ignored if iMethod is other than 0x1.
    • lPostDataSize is the length of pPostData in bytes and must be set accurately if you are posting data.
    • pPostHeaders is a NULL terminated string of characters specifying additional headers you wish to post to the server specified in pURL. This argument is ignored if you are not posting data, or if pPostData is empty. If you have more than one header in pPostHeaders, be sure and seperate them with a carriage return line feed pair. Do not append a carriage return line feed pair to the final header listed. If you specify pPostData to be an empty string, and you are posting, then the header

      Content-type: application/x-www-form-urlencoded

      will be used by default.
    Return Value:
    

    • BOOL is either 0 (FALSE) indicating failure to initiate the load or non-zero (TRUE) indicating success. In the case of failure, you should check the value returned by the method GetStatus to determine the exact reasons of the failure.
    Description:
    When this method fails, it is possible that Netscape is busy and desires the mehtod Open to be called again; check the return value of the method GetStatus for this information. Calling this method while another URL is currently loading is the same as calling the method Close on the previous load and then Open.
18. short Read(BSTR* pBuffer, short iAmount);
    
    Purpose:
    Read data retrieved by Netscape.
    Arguments:
    

    • pBuffer is a buffer in which to store the read information.
    • iAmount is the maximum amount of data to store in pBuffer.
    Return Value:
    

    • short is the amount of data actually stored in the buffer by Netscape. When short is -1, then there is no data left to be read. When short is 0, then there is currently no data to be read, though more may be available later.
    Description:
    This method should only be called between a successful call to Open and a call to Close. On a return value of -1, you can check the status of the read via a call to GetStatus. BSTRs are normally prepended with the length of the BSTR buffer size, this value is not modified in any way by Netscape. Refer to the return value when deciding how much data was actually placed in the buffer by Netscape.
19. CString Resolve(LPCTSTR pBase, LPCTSTR pRelative);
    
    Purpose:
    Generate an absolute (fully qualified) URL.
    Arguments:
    

    • pBase is the base URL.
    • pRelative is the URL relative to the base URL.
    Return Value:
    

    • CString is the resultant absolute URL generated.
    Description:
    Use this function to resolve a relative URL with respect to the base URL. This method is available at any time during the lifetime of the Netscape.Network.1 object. This method will correctly resolve unknown protocol types, given that they follow the same paradigm of all standard URLs.
20. void SetFlagFancyFTP(BOOL);
    
    Purpose:
    Inform Netscape wether or not FTP file listings will contian information such as file size, file type, etc.
    Arguments:
    

    • BOOL is TRUE if FTP file listings should contain fancy information, FALSE if a simple file listing will be generated.
    Description:
    This method is provided since not all FTP servers return information which is coherently interpreted by Netscape.
21. void SetFlagFancyNews(BOOL);
    
    Purpose:
    Inform Netscape wither or not Newsgroup listings should also contain descriptions.
    Arguments:
    

    • BOOL is TRUE if Netscape should only list newsgroups with descriptions. FALSE if Netscape should list all newsgroups.
    Description:
    This method is provided since not all newsgroups have descriptions and will not show up in a Newsgroup listing produced by Netscape.
22. void SetFlagShowAllNews(BOOL);
    
    Purpose:
    Inform Netscape wether or not all news articles will be listed when invoking Open with a news URL.
    Arguments:
    

    • BOOL is TRUE if all news articles should be listed. FALSE if only unread news articles should be listed.
23. void SetPassword(LPCTSTR);
    
    Purpose:
    Set the current password in the Netscape.Network.1 object.
    Arguments:
    

    • LPCTSTR is the string containing the password to be used if required in subsequent Opens.
    Description:
    Use this method to set the username for a load which requires access authorization. Invoking this method with an empty string will effectively erase the current password being used. Passwords are not shared between Netscape.Network.1 instances.
24. void SetUsername(LPCTSTR);
    
    Purpose:
    Set the current username in the Netscape.Network.1 object.
    Arguments:
    

    • LPCTSTR is a string containing the username to be used if required in subsequent Opens.
    Description:
    Use this method to set the username for a load which requires access authorization. Invoking this method with an empty string will effectively erase the current username being used. Usernames are not shared between Netscape.Network.1 instances.

Netscape.Registry.1 is meant to provide a unified interface for external applications to register themselves with Netscape as a viewer for a particular MIME type and/or as a handler of a particular protocol access type. Once an application uses this automation object to register itself with Netscape, the registration is persistant over sessions of Netscape. All registered viewers and protocol handlers must become an OLE Automation server by implementing automation objects that are in turn used by Netscape to send the appropriate data to the viewer/protocol handler; the exact requirements of these automation objects are listed in the sections Implementing External Streaming Viewers and Implementing External Protocol Handlers.

The methods of Netscape.Registry.1 are:

1. BOOL RegisterViewer(LPCTSTR pMimeType, LPCTSTR pRegistryName);
   
   Purpose:
   Register an OLE automation server to act as a streaming viewer for a particular MIME type.
   Arguments:
   

   • pMimeType is the MIME type of data which the external streaming viewer would like to handle.
   • pRegistryName is the name of the OLE Automation Server as known by the system registry. This is not a UUID, but is the human readable server name.
   Return Value:
   

   • BOOL is TRUE if the registration was successful. FALSE if the registration was not successful (there is already another viewer registered for this MIME type, possibly the same viewer).
   Description:
   Use this method to register an external viewer for a particular MIME type. Netscape will in turn create a pRegistryName object when this MIME type is encountered, and stream the data for this MIME type to the external viewer (see Implementing External Streaming Viewers). A viewer can be registered to handle several different MIME types. It is ill advised to register a streaming viewer for MIME types which Netscape can handle internally, though it is possible.
2. BOOL RegisterProtocol(LPCTSTR pProtcol, LPCTSTR pRegistryName);
   
   Purpose:
   Register an OLE automation server to act as a protocol handler for a particular protocol type.
   Arguments:
   

   • pProtocol is the protocl type (ftp, gopher, news, mailto, etc) which the external protocol handler would like to handle.
   • pRegistryName is the name of the OLE Automation Server as known by the system registry. This is not a UUID, but is the human readable server name.
   Return Value:
   

   • BOOL is TRUE if the registration was successful. FALSE if the registration failed (this is already another protocol handler registered for this protocol type, possibly the same protocol handler).
   Description:
   Use this method to register an external protocol handler for a particular protocol type. Netscape will in turn create a pRegistryName object when this protocol type is encountered, and hand the URL over to the protocol handler taking no further action. A protocol handler can be registered to handle several different protocol types. The protocol type does not need to be one which Netscape can currently handle internally. It is ill advised to register a protocol handler for types which Netscape can handle internally, though it is possible.

External streaming viewers are applications external to Netscape which implement a special automation object which is made known to Netscape through Netscape.Registry.1's member RegisterViewer. After this automation object has been registered with Netscape, Netscape can then stream data of the appropriate MIME type to that object while downloading the data from the network. Below is a description of the members which the automation object must support, and at the end of this document you will find an example ODL file to give you the more intimate details regarding the OLE aspects of the implementation.

Netscape will create the automation object when it has data to stream to the object. In usual OLE Automation applications, the application will attempt to hide itself if not previously visible (not already running), and this may or may not be the behavior you wish your application to exhibit. Also, when Netscape is finished streaming data to the automation object, Netscape will release the object. The usual behavior would be to shut down the application if no other OLE locks are present, which may or may not be the behavior you wish your application to exhibit. Such details are left up to you so that you may correctly handle the specific needs of your application.

The methods of a streaming viewer are:

1. void Close(short iStatus);
   
   Purpose:
   To inform the viewer that the download is now complete.
   Arguments:
   

   • iStatus is 0 when the stream was successfully transferred, -1 when the stream was not fully transferred (interrupted).
   Description:
   Netscape invokes this method just before it deletes the streaming viewer object, informing the streaming viewer of wether or not it received a completed stream.
2. short Initialize(LPCTSTR pMimeType, LPCTSTR pUrl);
   
   Purpose:
   Initialize the external streaming viewer.
   Arguments:
   

   • pMimeType is the MIME type that Netscape is about to stream to the viewer.
   • pUrl is the URL where the stream originated.
   Return Value:
   

   • short is 0 on failure to initialize the external streaming viewer, and should otherwise be 1 indicating acceptance of the incoming data.
   Description:
   This method is the first invoked by Netscape when a stream of pMimeType is ready the external streaming viewer. If the viewer decides it would not like to handle pUrl of pMimeType, then it should return 0. If the viewer returns success, then Netscape will begin calling all other methods of the external streaming viewer.
3. long Ready();
   
   Purpose:
   Query the external streaming viewer how much data it is ready to handle.
   Return Value:
   

   • long is the number of bytes the external streaming viewer is ready to handle. A value of 0 informs Netscape that it should try again later.
   Description:
   Netscape will always invoke this method, possible several times, before it invokes Write. This is to ensure that Netscape will not overload the external streaming viewer with data.
4. void Write(BSTR* pData, long lBytes);
   
   Purpose:
   Stream data to the external streaming viewer.
   Arguments:
   

   • pData is a buffer containing the data to stream.
   • lBytes is the number of bytes contained in the buffer.
   Description:
   Netscape will never invoke this method without first invoking Ready. Netscape will invoke this method with no more data than is reported by Ready. Always refer to lBytes when figuring out the amount of data in pData, as the BSTR may contain binary data and the amount of data may be less than the length reported by BSTR functions.

External protocol handlers are applications external to Netscape which implement a special automation object which is made known to Netscape through Netscape.Registry.1's member RegisterProtocol. After this automation object has been registered with Netscape, Netscape can then tell the external protocol handler to open a URL with a particular protocol (access type; i.e. http, gopher, ftp, news, mailto, and others). Available protocol types need not stay within the bounds of the Netscape internally handled protocol types. Please be aware that Netscape will not be able to handle the unknown protocol type internally without the aid and registration of your external protocol handler(s). If no such registration is present, the user will receive an invalid URL error message. Bleow is a description of the members which the automation object must support, and at the end of this document you will find an example ODL file to give you the more intimate details regarding the OLE implementation aspects of the object.

Netscape will create the automation object when it has a URL of the protocol type which is handled by the object. In usual OLE Automation applications, the applciation will attempt to hide itself if not previously visible (not already running), and this may or may not be the behavior you wish your applciation to exhibit. Also, when Netscape has handed the URL over to the automation object, the object will be released by Netscape. The usual behavior would be to shut down the applciation if no other OLE locks are present, which will almost certainly not be the behavior you wish your applciation to exhibit. Such details are left up to you so that you may correctly handle the specific needs of your applciation.

The mehtods of a protocol handler are:

1. short Initialize(LPCTSTR pProtocol, LPCTSTR pUrl);
   
   Purpose:
   Initialize an external protocol handler to receive a URL.
   Arguments:
   

   • pProtocol is the protocol which Netscape is wanting the external protocol handler to handle.
   • pUrl is the URL from which the protocol was extracted.
   Return Value:
   

   • short is 1 if the external protocol handler would like to handle the protocol, and is 0 if otherwise.
   Description:
   Netscape will invoke this method first if it encounters a protocol which an external protocol handler has registered itself to handle. If the external protocol handler decides that it would not like to handle the protocol type or URL, then it should return 0. If the protocl handler returns success, then Netscape will begin invoking the other methods of the protocol handler.
2. void Open(LPCTSTR pUrl);
   
   Purpose:
   Informs the external protocol handler that it should open a URL.
   Arguments:
   

   • pUrl is the URL which Netscape would like the external protocol handler to handle.
   Description:
   Once Netscape has invoked this method, the external protocol handler object with be deleted by Netscape. Netscape assumes that the protocol handler took appropriate actions to successfully open the URL, and/or to report the status to the user.

NETSCAPE.ODL

The file used to generate the type library for the Netscape Navigator showing the exact UUIDs, OLE data types, dispatch interfaces, method and property names, etc.

VIEWER.ODL

An example file which should give you the details needed for a correct implementation of an external streaming viewer.

PROTOCOL.ODL

An example file which should give you the details needed for a correct implementation of an external protocol handler.