nsXPCOM.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:14k
源码类别:

PlugIns编程

开发平台:

Visual C++

  1. /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is mozilla.org code.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Benjamin Smedberg <benjamin@smedbergs.us>
  24.  *
  25.  * Alternatively, the contents of this file may be used under the terms of
  26.  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27.  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28.  * in which case the provisions of the GPL or the LGPL are applicable instead
  29.  * of those above. If you wish to allow use of your version of this file only
  30.  * under the terms of either the GPL or the LGPL, and not to allow others to
  31.  * use your version of this file under the terms of the MPL, indicate your
  32.  * decision by deleting the provisions above and replace them with the notice
  33.  * and other provisions required by the GPL or the LGPL. If you do not delete
  34.  * the provisions above, a recipient may use your version of this file under
  35.  * the terms of any one of the MPL, the GPL or the LGPL.
  36.  *
  37.  * ***** END LICENSE BLOCK ***** */
  38. #ifndef nsXPCOM_h__
  39. #define nsXPCOM_h__
  40. // Map frozen functions to private symbol names if not using strict API.
  41. #ifdef MOZILLA_INTERNAL_API
  42. # define NS_InitXPCOM2               NS_InitXPCOM2_P
  43. # define NS_InitXPCOM3               NS_InitXPCOM3_P
  44. # define NS_ShutdownXPCOM            NS_ShutdownXPCOM_P
  45. # define NS_GetServiceManager        NS_GetServiceManager_P
  46. # define NS_GetComponentManager      NS_GetComponentManager_P
  47. # define NS_GetComponentRegistrar    NS_GetComponentRegistrar_P
  48. # define NS_GetMemoryManager         NS_GetMemoryManager_P
  49. # define NS_NewLocalFile             NS_NewLocalFile_P
  50. # define NS_NewNativeLocalFile       NS_NewNativeLocalFile_P
  51. # define NS_GetDebug                 NS_GetDebug_P
  52. # define NS_GetTraceRefcnt           NS_GetTraceRefcnt_P
  53. # define NS_Alloc                    NS_Alloc_P
  54. # define NS_Realloc                  NS_Realloc_P
  55. # define NS_Free                     NS_Free_P
  56. #endif
  57. #include "nscore.h"
  58. #include "nsXPCOMCID.h"
  59. class nsAString;
  60. class nsACString;
  61. class nsIModule;
  62. class nsIComponentManager;
  63. class nsIComponentRegistrar;
  64. class nsIServiceManager;
  65. class nsIFile;
  66. class nsILocalFile;
  67. class nsIDirectoryServiceProvider;
  68. class nsIMemory;
  69. class nsIDebug;
  70. class nsITraceRefcnt;
  71. /**
  72.  * Every XPCOM component implements this function signature, which is the
  73.  * only entrypoint XPCOM uses to the function.
  74.  *
  75.  * @status FROZEN
  76.  */
  77. typedef nsresult (PR_CALLBACK *nsGetModuleProc)(nsIComponentManager *aCompMgr,
  78.                                                 nsIFile* location,
  79.                                                 nsIModule** return_cobj);
  80. /**
  81.  * Initialises XPCOM. You must call one of the NS_InitXPCOM methods
  82.  * before proceeding to use xpcom. The one exception is that you may
  83.  * call NS_NewLocalFile to create a nsIFile.
  84.  * 
  85.  * @status FROZEN
  86.  *
  87.  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE> 
  88.  *       to create the file object you supply as the bin directory path in this
  89.  *       call. The function may be safely called before the rest of XPCOM or 
  90.  *       embedding has been initialised.
  91.  *
  92.  * @param result           The service manager.  You may pass null.
  93.  *
  94.  * @param binDirectory     The directory containing the component
  95.  *                         registry and runtime libraries;
  96.  *                         or use <CODE>nsnull</CODE> to use the working
  97.  *                         directory.
  98.  *
  99.  * @param appFileLocationProvider The object to be used by Gecko that specifies
  100.  *                         to Gecko where to find profiles, the component
  101.  *                         registry preferences and so on; or use
  102.  *                         <CODE>nsnull</CODE> for the default behaviour.
  103.  *
  104.  * @see NS_NewLocalFile
  105.  * @see nsILocalFile
  106.  * @see nsIDirectoryServiceProvider
  107.  *
  108.  * @return NS_OK for success;
  109.  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
  110.  *         which can happen if XPCOM is reloaded, but did not completly
  111.  *         shutdown. Other error codes indicate a failure during
  112.  *         initialisation.
  113.  */
  114. extern "C" NS_COM nsresult
  115. NS_InitXPCOM2(nsIServiceManager* *result, 
  116.               nsIFile* binDirectory,
  117.               nsIDirectoryServiceProvider* appFileLocationProvider);
  118. /**
  119.  * Some clients of XPCOM have statically linked components (not dynamically
  120.  * loaded component DLLs), which can be passed to NS_InitXPCOM3 using this
  121.  * structure.
  122.  *
  123.  * @status FROZEN
  124.  */
  125. struct nsStaticModuleInfo {
  126.   const char      *name;
  127.   nsGetModuleProc  getModule;
  128. };
  129. /**
  130.  * Initialises XPCOM with static components. You must call one of the
  131.  * NS_InitXPCOM methods before proceeding to use xpcom. The one
  132.  * exception is that you may call NS_NewLocalFile to create a nsIFile.
  133.  * 
  134.  * @status FROZEN
  135.  *
  136.  * @note Use <CODE>NS_NewLocalFile</CODE> or <CODE>NS_NewNativeLocalFile</CODE> 
  137.  *       to create the file object you supply as the bin directory path in this
  138.  *       call. The function may be safely called before the rest of XPCOM or 
  139.  *       embedding has been initialised.
  140.  *
  141.  * @param result           The service manager.  You may pass null.
  142.  *
  143.  * @param binDirectory     The directory containing the component
  144.  *                         registry and runtime libraries;
  145.  *                         or use <CODE>nsnull</CODE> to use the working
  146.  *                         directory.
  147.  *
  148.  * @param appFileLocationProvider The object to be used by Gecko that specifies
  149.  *                         to Gecko where to find profiles, the component
  150.  *                         registry preferences and so on; or use
  151.  *                         <CODE>nsnull</CODE> for the default behaviour.
  152.  *
  153.  * @param staticComponents An array of static components. Passing null causes
  154.  *                         default (builtin) components to be registered, if
  155.  *                         present.
  156.  * @param componentCount   Number of elements in staticComponents
  157.  *
  158.  * @see NS_NewLocalFile
  159.  * @see nsILocalFile
  160.  * @see nsIDirectoryServiceProvider
  161.  * @see XRE_GetStaticComponents
  162.  *
  163.  * @return NS_OK for success;
  164.  *         NS_ERROR_NOT_INITIALIZED if static globals were not initialized,
  165.  *         which can happen if XPCOM is reloaded, but did not completly
  166.  *         shutdown. Other error codes indicate a failure during
  167.  *         initialisation.
  168.  */
  169. extern "C" NS_COM nsresult
  170. NS_InitXPCOM3(nsIServiceManager* *result, 
  171.               nsIFile* binDirectory,
  172.               nsIDirectoryServiceProvider* appFileLocationProvider,
  173.               nsStaticModuleInfo const *staticComponents,
  174.               PRUint32 componentCount);
  175. /**
  176.  * Shutdown XPCOM. You must call this method after you are finished
  177.  * using xpcom. 
  178.  *
  179.  * @status FROZEN
  180.  *
  181.  * @param servMgr           The service manager which was returned by NS_InitXPCOM.
  182.  *                          This will release servMgr.  You may pass null.
  183.  *
  184.  * @return NS_OK for success;
  185.  *         other error codes indicate a failure during initialisation.
  186.  *
  187.  */
  188. extern "C" NS_COM nsresult
  189. NS_ShutdownXPCOM(nsIServiceManager* servMgr);
  190. /**
  191.  * Public Method to access to the service manager.
  192.  * 
  193.  * @status FROZEN
  194.  * @param result Interface pointer to the service manager 
  195.  *
  196.  * @return NS_OK for success;
  197.  *         other error codes indicate a failure during initialisation.
  198.  *
  199.  */
  200. extern "C" NS_COM nsresult
  201. NS_GetServiceManager(nsIServiceManager* *result);
  202. /**
  203.  * Public Method to access to the component manager.
  204.  * 
  205.  * @status FROZEN
  206.  * @param result Interface pointer to the service 
  207.  *
  208.  * @return NS_OK for success;
  209.  *         other error codes indicate a failure during initialisation.
  210.  *
  211.  */
  212. extern "C" NS_COM nsresult
  213. NS_GetComponentManager(nsIComponentManager* *result);
  214. /**
  215.  * Public Method to access to the component registration manager.
  216.  * 
  217.  * @status FROZEN
  218.  * @param result Interface pointer to the service 
  219.  *
  220.  * @return NS_OK for success;
  221.  *         other error codes indicate a failure during initialisation.
  222.  *
  223.  */
  224. extern "C" NS_COM nsresult
  225. NS_GetComponentRegistrar(nsIComponentRegistrar* *result);
  226. /**
  227.  * Public Method to access to the memory manager.  See nsIMemory
  228.  * 
  229.  * @status FROZEN
  230.  * @param result Interface pointer to the memory manager 
  231.  *
  232.  * @return NS_OK for success;
  233.  *         other error codes indicate a failure during initialisation.
  234.  *
  235.  */
  236. extern "C" NS_COM nsresult
  237. NS_GetMemoryManager(nsIMemory* *result);
  238. /**
  239.  * Public Method to create an instance of a nsILocalFile.  This function
  240.  * may be called prior to NS_InitXPCOM.
  241.  * 
  242.  * @status FROZEN
  243.  * 
  244.  *   @param path       
  245.  *       A string which specifies a full file path to a 
  246.  *       location.  Relative paths will be treated as an
  247.  *       error (NS_ERROR_FILE_UNRECOGNIZED_PATH).       
  248.  *       |NS_NewNativeLocalFile|'s path must be in the 
  249.  *       filesystem charset.
  250.  *   @param followLinks
  251.  *       This attribute will determine if the nsLocalFile will auto
  252.  *       resolve symbolic links.  By default, this value will be false
  253.  *       on all non unix systems.  On unix, this attribute is effectively
  254.  *       a noop.  
  255.  * @param result Interface pointer to a new instance of an nsILocalFile 
  256.  *
  257.  * @return NS_OK for success;
  258.  *         other error codes indicate a failure.
  259.  */
  260. extern "C" NS_COM nsresult
  261. NS_NewLocalFile(const nsAString &path, 
  262.                 PRBool followLinks, 
  263.                 nsILocalFile* *result);
  264. extern "C" NS_COM nsresult
  265. NS_NewNativeLocalFile(const nsACString &path, 
  266.                       PRBool followLinks, 
  267.                       nsILocalFile* *result);
  268. /**
  269.  * Allocates a block of memory of a particular size. If the memory cannot
  270.  * be allocated (because of an out-of-memory condition), null is returned.
  271.  *
  272.  * @status FROZEN
  273.  *
  274.  * @param size   The size of the block to allocate
  275.  * @result       The block of memory
  276.  * @note         This function is thread-safe.
  277.  */
  278. extern "C" NS_COM void*
  279. NS_Alloc(PRSize size);
  280. /**
  281.  * Reallocates a block of memory to a new size.
  282.  *
  283.  * @status FROZEN
  284.  *
  285.  * @param ptr     The block of memory to reallocate. This block must originally
  286.                   have been allocated by NS_Alloc or NS_Realloc
  287.  * @param size    The new size. If 0, frees the block like NS_Free
  288.  * @result        The reallocated block of memory
  289.  * @note          This function is thread-safe.
  290.  *
  291.  * If ptr is null, this function behaves like NS_Alloc.
  292.  * If s is the size of the block to which ptr points, the first min(s, size)
  293.  * bytes of ptr's block are copied to the new block. If the allocation
  294.  * succeeds, ptr is freed and a pointer to the new block is returned. If the
  295.  * allocation fails, ptr is not freed and null is returned. The returned
  296.  * value may be the same as ptr.
  297.  */
  298. extern "C" NS_COM void*
  299. NS_Realloc(void* ptr, PRSize size);
  300. /**
  301.  * Frees a block of memory. Null is a permissible value, in which case no
  302.  * action is taken.
  303.  *
  304.  * @status FROZEN
  305.  *
  306.  * @param ptr   The block of memory to free. This block must originally have
  307.  *              been allocated by NS_Alloc or NS_Realloc
  308.  * @note        This function is thread-safe.
  309.  */
  310. extern "C" NS_COM void
  311. NS_Free(void* ptr);
  312. /**
  313.  * Categories (in the category manager service) used by XPCOM:
  314.  */
  315. /**
  316.  * A category which is read after component registration but before
  317.  * the "xpcom-startup" notifications. Each category entry is treated
  318.  * as the contract ID of a service which implements
  319.  * nsIDirectoryServiceProvider. Each directory service provider is
  320.  * installed in the global directory service.
  321.  *
  322.  * @status FROZEN
  323.  */
  324. #define XPCOM_DIRECTORY_PROVIDER_CATEGORY "xpcom-directory-providers"
  325. /**
  326.  * A category which is read after component registration but before
  327.  * NS_InitXPCOM returns. Each category entry is treated as the contractID of
  328.  * a service: each service is instantiated, and if it implements nsIObserver
  329.  * the nsIObserver.observe method is called with the "xpcom-startup" topic.
  330.  *
  331.  * @status FROZEN
  332.  */
  333. #define NS_XPCOM_STARTUP_CATEGORY "xpcom-startup"
  334. /**
  335.  * Observer topics (in the observer service) used by XPCOM:
  336.  */
  337. /**
  338.  * At XPCOM startup after component registration is complete, the
  339.  * following topic is notified. In order to receive this notification,
  340.  * component must register their contract ID in the category manager,
  341.  *
  342.  * @see NS_XPCOM_STARTUP_CATEGORY
  343.  * @status FROZEN
  344.  */
  345. #define NS_XPCOM_STARTUP_OBSERVER_ID "xpcom-startup"
  346. /**
  347.  * At XPCOM shutdown, this topic is notified. All components must
  348.  * release any interface references to objects in other modules when
  349.  * this topic is notified.
  350.  *
  351.  * @status FROZEN
  352.  */
  353. #define NS_XPCOM_SHUTDOWN_OBSERVER_ID "xpcom-shutdown"
  354. /**
  355.  * This topic is notified when an entry was added to a category in the
  356.  * category manager. The subject of the notification will be the name of
  357.  * the added entry as an nsISupportsCString, and the data will be the
  358.  * name of the category.
  359.  *
  360.  * @status FROZEN
  361.  */
  362. #define NS_XPCOM_CATEGORY_ENTRY_ADDED_OBSERVER_ID 
  363.   "xpcom-category-entry-added"
  364. /**
  365.  * This topic is notified when an entry was removed from a category in the
  366.  * category manager. The subject of the notification will be the name of
  367.  * the removed entry as an nsISupportsCString, and the data will be the
  368.  * name of the category.
  369.  *
  370.  * @status FROZEN
  371.  */
  372. #define NS_XPCOM_CATEGORY_ENTRY_REMOVED_OBSERVER_ID 
  373.   "xpcom-category-entry-removed"
  374. /**
  375.  * This topic is notified when an a category was cleared in the category
  376.  * manager. The subject of the notification will be the category manager,
  377.  * and the data will be the name of the cleared category.
  378.  *
  379.  * @status FROZEN
  380.  */
  381. #define NS_XPCOM_CATEGORY_CLEARED_OBSERVER_ID "xpcom-category-cleared"
  382. extern "C" NS_COM nsresult
  383. NS_GetDebug(nsIDebug* *result);
  384. extern "C" NS_COM nsresult
  385. NS_GetTraceRefcnt(nsITraceRefcnt* *result);
  386. #endif