How to Mark an Interface as Frozen
Please follow the guidelines below before marking an interface as frozen.
For starters, take a look at the IDL
interface rules document. Follow the rules in that document
and help us maintain consistency and correctness by sending your
comments and/or additions to this document to the author or current
maintainer.
Here's a general outline of what an IDL file of a
FROZEN interface should look like - specifically
what sections we'd like to have and their
order:
- The License section (Use a boilerplate to make it easier)
#include's of any other required IDL files- Forward declarations of other interfaces referred to in the methods of the current interface
- A general description of the current interface's purpose/functionality
- "@status FROZEN" keyword in the section. [Another important guideline to remember here is the requirement of having one and only one interface per IDL file]
- Descriptions of each of the
methods in the interface.
When writing descriptions for sections 5 and 6 above please follow the JavaDoc guidelines.
Here's a sample template which follows the guidelines set above:
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corp.
* Portions created by the Initial Developer are Copyright (C) 2003
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
Adam Lock <adamlock@netscape.com>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
* * Contributor(s):
*/
#include "nsISupports.idl"
interface nsIDOMNode;
/**
* An optional interface for embedding clients wishing
to receive
* notifications for when a tooltip should be displayed
or removed.
* The embedder implements this interface on the web browser
chrome
* object associated with the window that notifications
are required
* for.
*
* @status FROZEN
*/
[uuid(44b78386-1dd2-11b2-9ad2-e4eee2ca1916)]
interface nsITooltipListener : nsISupports
{
/**
* Called when a tooltip should be displayed.
*
* @param aXCoords The tooltip left edge X coordinate.
* @param aYCoords The tooltip top edge Y coordinate.
* @param aTipText The text to display in the tooltip, typically obtained
* from the TITLE attribute of the node (or containing parent)
* over which the pointer has been positioned.
*
* @note
* Coordinates are specified in pixels, relative to the top-left
* corner of the browser area.
*
* @return NS_OK Tooltip was displayed.
* @return Other No tooltip was displayed.
*/
void onShowTooltip(in long aXCoords, in long aYCoords,
in wstring aTipText);
/**
* Called when the tooltip should be hidden, either because the pointer
* has moved or the tooltip is to be hidden.
*/
void onHideTooltip();
};
How to mark a service/component as frozen
For each frozen service or public component create a corresponding header file which has the following:
- #includes for each of the interfaces it supports. This allows consumers to simply include the 'component' header file when using a component without having to explicitly include all of the interface headers...
- Definition of the Contract-id (and Class-id if necessary) for the component instance.
- Documentation about the component [Please follow the guidelines in "How to mark an interface as frozen" mentioned above as applicable]
- Any other component specific code and/or defines.
Required Makefile.in Changes to support SDK
In order to maintain an up-to-date SDK, the build system provides a way to export frozen interface, frozen headers, and binaries into an SDK directory in dist.
The layout of this SDK is roughly the following:
dist/sdk/module/idl
dist/sdk/module/include
dist/sdk/module/bin
If you would like to have this new frozen interface part of the sdk, the following build variables will help you. There are three define supported in gmake (Makefile.in) which aide in the construction of a SDK distribution.
SDK_HEADERS
SDK_HEADERS extends the EXPORT define. In addition to exporting files listed in SDK_HEADERS to dist/include/module, we create a directory dist/sdk/module/include where these files are duplicated. This define is meant to only include headers which are part of the SDK. You may use this define with the EXPORT define.
SDK_XPIDLSRCS
SDK_XPIDLSRCS extends the XPIDLSRCS. In addition to exporting IDL to dist/idl/module and building typelibs which are pushed in dist/bin, this define makes copies of the IDL in dist/sdk/module/idl and copies of the type lib in dist/sdk/module/bin. (Currently type libraries are NOT copied into dist/sdk/. We need to get this fixed.).
SDK_BINARY
SDK_BINARY exports files into dist/sdk/module/bin. These files are commonly libraries and executables.
You can take a look at mozilla/xpcom as an example of usage.
Announcements, Announcements, Announcements!
When you think that you are ready: Communicate!We have created a mailing list that is meant to be a low volume notification of API changes. Gecko embedders and component developers are encouraged to sign up so that they may receive these notifications.
When you are in the process of freezing an interface you should have mail sent to this mailing list with the informmation regarding the scope of the change, required modifications to exist code, ect. This is to keep people that are building software using Mozilla in the know.
So, when you start thinking about freezing an inteface, send a mail. When you have frozen an interface, send a mail.
To send mail to this mailing list, please contact Doug Turner or Juan Jose Mata. You must include a bug numbers, and summary of changes.