Compare Revisions

Using nsIDirectoryService

Revision 7418:

Revision 7418 by Wjjohnst on

Revision 7419:

Revision 7419 by Psobolik on

Title:
Using nsIDirectoryService
Using nsIDirectoryService
Slug:
Using_nsIDirectoryService
Using_nsIDirectoryService
Tags:
NeedsTechnicalReview, Extensions, XPCOM, NeedsMarkupWork, NeedsEditorialReview
NeedsTechnicalReview, Extensions, XPCOM, NeedsMarkupWork, NeedsEditorialReview
Content:

Revision 7418
Revision 7419
n8      Content formerly at http://www.mozilla.org/projects/xpcom/nn8      Content formerly at <a class=" external" href="http://www.m
>sDirectoryService.html>ozilla.org/projects/xpcom/nsDirectoryService.html" rel="freelink"
 >>http://www.mozilla.org/projects/xpco...ryService.html</a>
n14      nsDirectoryService implements the {{template.Interface("nsIn14      nsDirectoryService implements the {{ Interface("nsIProperti
>Properties")}} interface. This implementation will allow to you <>es") }} interface. This implementation will allow to you <code>Ge
>code>Get()</code>, <code>Set()</code>, <code>Define()</code>, and>t()</code>, <code>Set()</code>, <code>Define()</code>, and <code>
> <code>Undefine()</code> {{template.Interface("nsIFile")}}.>Undefine()</code> {{ Interface("nsIFile") }}.
n23      First, you must know what the string key (or property) is tn23      First, you must know what the string key (or property) is t
>hat refers to this locations. Header files containing known keys >hat refers to this locations. Header files containing known keys 
>are listed in the <a href="#Known_Locations">Known Locations</a> >are listed in the <a href="#Known_Locations">Known Locations</a> 
>section of this document. Bare in mind, that this list is not sta>section of this document. Bear in mind, that this list is not sta
>tic. Components can add and remove locations at their will.>tic. Components can add and remove locations at their will.
n64      You can directly add a new {{template.Interface("nsIFile")}n64      You can directly add a new {{ Interface("nsIFile") }} with 
>} with any property string using the {{template.Interface("nsIPro>any property string using the {{ Interface("nsIProperties") }} in
>perties")}} interface:>terface:
n72      Now, if your cost is too high to set all of these propertien72      Now, if your cost is too high to set all of these propertie
>s at once, you can register to be a callback that can provide an >s at once, you can register to be a callback that can provide an 
>nsIFile. To do this, you must get the implementation again like a>nsIFile. To do this, you must get the implementation again like a
>bove. When you have it, <a href="en/NsISupports/QueryInterface">Q>bove. When you have it, <a href="en/NsISupports/QueryInterface">Q
>ueryInterface</a> for the {{template.Interface("nsIDirectoryServi>ueryInterface</a> for the {{ Interface("nsIDirectoryService") }} 
>ce")}} interface. Off of this interface there is a function, <cod>interface. Off of this interface there is a function, <code>regis
>e>registerProvider</code> which will allow you to register a {{te>terProvider</code> which will allow you to register a {{ Interfac
>mplate.Interface("nsIDirectoryServiceProvider")}}, which implemen>e("nsIDirectoryServiceProvider") }}, which implements the <code>g
>ts the <code>getFile</code> callback function:>etFile</code> callback function:
n83      When the callback is called, it will be passed the string kn83      When the callback is called, it will be passed the string k
>ey, and should return an {{template.Interface("nsIFile")}}. The <>ey, and should return an {{ Interface("nsIFile") }}. The <code>pe
>code>persistant</code> flag allow you to specify if you want the >rsistant</code> flag allow you to specify if you want the <code>n
><code>nsDirectoryService</code> to cache this value. Most uses yo>sDirectoryService</code> to cache this value. Most uses you would
>u would want this to be true.> want this to be true.
n92      The {{template.Interface("nsIProperties")}} strings for curn92      The {{ Interface("nsIProperties") }} strings for currently 
>rently defined locations can be found in:>defined locations can be found in:
n106      Content formerly at http://www.mozilla.org/projects/xpcom/fn106      Content formerly at <a class=" external" href="http://www.m
>ile_locations.html>ozilla.org/projects/xpcom/file_locations.html" rel="freelink">htt
 >p://www.mozilla.org/projects/xpco...locations.html</a>
n112      The way in which Mozilla components locate special files ann112      The way in which Mozilla components locate special files an
>d directories has changed. In the past, this was done using {{tem>d directories has changed. In the past, this was done using {{ In
>plate.Interface("nsIFileLocator")}}. This component was a problem>terface("nsIFileLocator") }}. This component was a problem for em
> for embedding applications. Since it was a component and was loa>bedding applications. Since it was a component and was loaded imp
>ded implicitly by many other components, it was difficult to cust>licitly by many other components, it was difficult to customize. 
>omize. Customizing the locations is important if, for example, yo>Customizing the locations is important if, for example, your appl
>ur application already has a profile directory or other resource >ication already has a profile directory or other resource directo
>directories. You may wish that you could have Mozilla use these l>ries. You may wish that you could have Mozilla use these location
>ocations rather than requiring the same disk layout as SeaMonkey.>s rather than requiring the same disk layout as SeaMonkey. In ord
> In order to change these locations using {{template.Interface("n>er to change these locations using {{ Interface("nsIFileLocator")
>sIFileLocator")}} and still be able to use the same components di> }} and still be able to use the same components directory as an 
>rectory as an existing Mozilla installation, you had to make a co>existing Mozilla installation, you had to make a component with t
>mponent with the same ID as {{template.Interface("nsIFileLocator">he same ID as {{ Interface("nsIFileLocator") }} and then, after a
>)}} and then, after auto-registering components, manually registe>uto-registering components, manually register your own and replac
>r your own and replace the existing one -- all in all, a big pain>e the existing one -- all in all, a big pain.
>. 
n118      The new method uses {{template.Interface("nsIDirectoryServin118      The new method uses {{ Interface("nsIDirectoryService") }} 
>ce")}} to locate files and directories. Be sure to see the <a hre>to locate files and directories. Be sure to see the <a href="en/N
>f="en/NsDirectoryService">documentation</a> on the service itself>sDirectoryService">documentation</a> on the service itself. This 
>. This document will focus on how the service is used and how to >document will focus on how the service is used and how to customi
>customize it. Briefly, {{template.Interface("nsIDirectoryService">ze it. Briefly, {{ Interface("nsIDirectoryService") }} uses "prov
>)}} uses "providers" of type {{template.Interface("nsIDirectorySe>iders" of type {{ Interface("nsIDirectoryServiceProvider") }} to 
>rviceProvider")}} to provide file locations. When the service is >provide file locations. When the service is asked for a file loca
>asked for a file location, it goes through its list of providers >tion, it goes through its list of providers asking each if it kno
>asking each if it knows the requested location until it finds one>ws the requested location until it finds one that does. Once the 
> that does. Once the service finds a location, if the provider sa>service finds a location, if the provider says that the location 
>ys that the location is persistent, the service will cache that l>is persistent, the service will cache that location so it is very
>ocation so it is very quick on subsequent calls. Different provid> quick on subsequent calls. Different providers can provide certa
>ers can provide certain locations that are relevant to them. For >in locations that are relevant to them. For example, in SeaMonkey
>example, in SeaMonkey, the profile service is a provider for loca>, the profile service is a provider for locations that are relati
>tions that are relative to the current profile.>ve to the current profile.
n127      The {{template.Interface("nsIProperties")}} keywords that yn127      The {{ Interface("nsIProperties") }} keywords that you will
>ou will use to get locations are defined in two places.> use to get locations are defined in two places.
n139      If Mozilla's Components directory is not in the same directn139      If Mozilla's Components directory is not in the same direct
>ory as your process, you will need to set the /bin directory as d>ory as your process, you will need to set the /bin directory as d
>escribed above. In this case you will also need to tell the syste>escribed above. In this case you will also need to tell the syste
>m of the location of DLLs which are linked against. This aspect o>m of the location of DLLs which are linked against. This aspect o
>f file location is not related to {{template.Interface("nsIDirect>f file location is not related to {{ Interface("nsIDirectoryServi
>oryService")}}, but needs mention here.>ce") }}, but needs mention here.
n154      The first group listed is for locations that are relative tn154      The first group listed is for locations that are relative t
>o the application. For instance, the name and location of the chr>o the application. For instance, the name and location of the chr
>ome folder, or the default location of user profiles. The {{templ>ome folder, or the default location of user profiles. The {{ Inte
>ate.Interface("nsIDirectoryServiceProvider")}} which normally pro>rface("nsIDirectoryServiceProvider") }} which normally provides t
>vides these locations is at <a class="external" href="http://lxr.>hese locations is at <a class="external" href="http://lxr.mozilla
>mozilla.org/seamonkey/source/xpcom/io/">mozilla/xpcom/io/</a>. Th>.org/seamonkey/source/xpcom/io/">mozilla/xpcom/io/</a>. This prov
>is provider is installed by SeaMonkey after initializing XPCOM. I>ider is installed by SeaMonkey after initializing XPCOM. It is al
>t is also installed by default by NS_InitEmbedding.>so installed by default by NS_InitEmbedding.
n157      The second group listed is for locations which are relativen157      The second group listed is for locations which are relative
> to the current user profile. In SeaMonkey, the profile service i> to the current user profile. In SeaMonkey, the profile service i
>s an {{template.Interface("nsIDirectoryServiceProvider")}} and it>s an {{ Interface("nsIDirectoryServiceProvider") }} and it provid
> provides these locations. There are some cases in embedding in w>es these locations. There are some cases in embedding in which di
>hich distinct user profiles are not needed, however prefs and his>stinct user profiles are not needed, however prefs and history an
>tory and such are needed. In this case, the {{template.Interface(>d such are needed. In this case, the {{ Interface("nsIDirectorySe
>"nsIDirectoryServiceProvider")}} implementation at <a class="exte>rviceProvider") }} implementation at <a class="external" href="ht
>rnal" href="http://lxr.mozilla.org/seamonkey/source/profile/dirse>tp://lxr.mozilla.org/seamonkey/source/profile/dirserviceprovider/
>rviceprovider/">mozilla/profile/dirserviceprovider/</a> can be us>">mozilla/profile/dirserviceprovider/</a> can be used. If it is u
>ed. If it is used, it is used <i>instead</i> of the profile servi>sed, it is used <i>instead</i> of the profile service, thus savin
>ce, thus saving some footprint.>g some footprint.
n163      Although you can change locations one at a time by using thn163      Although you can change locations one at a time by using th
>e {{template.Interface("nsIProperties")}} interface of nsDirector>e {{ Interface("nsIProperties") }} interface of nsDirectoryServic
>yService, you can also install your own {{template.Interface("nsI>e, you can also install your own {{ Interface("nsIDirectoryServic
>DirectoryServiceProvider")}} to control them en masse. To do this>eProvider") }} to control them en masse. To do this for applicati
> for application-level locations, create a provider based on appf>on-level locations, create a provider based on appfilelocprovider
>ilelocprovider. This object has to implement the {{template.Inter>. This object has to implement the {{ Interface("nsISupports") }}
>face("nsISupports")}} and {{template.Interface("nsIDirectoryServi> and {{ Interface("nsIDirectoryServiceProvider") }} interfaces. I
>ceProvider")}} interfaces. It does not need to be a component - i>t does not need to be a component - it can be a static lib, a sou
>t can be a static lib, a source file in your project - whatever. >rce file in your project - whatever. Just construct it, pass it t
>Just construct it, pass it to NS_InitEmbedding and it will be ins>o NS_InitEmbedding and it will be installed. If you are not using
>talled. If you are not using NS_InitEmbedding, you will have to c> NS_InitEmbedding, you will have to construct it and register it 
>onstruct it and register it yourself using {{wiki.template('Inter>yourself using {{ Interface-method("nsIDirectoryService", "regist
>face-method'[ "nsIDirectoryService", "registerProvider" ])}}. I>erProvider") }}. If you are registering it yourself it is very im
>f you are registering it yourself it is very important to registe>portant to register it <b>immediately</b> after calling NS_InitXP
>r it <b>immediately</b> after calling NS_InitXPCOM. There are thi>COM. There are things in the startup process that need these loca
>ngs in the startup process that need these locations at a very ea>tions at a very early point - even before registering components.
>rly point - even before registering components. 
t181        <li>Authors: <a class="external" href="mailto:ccarlen@nett181        <li>Authors: <a class="link-mailto" href="mailto:ccarlen@
>scape.com">Conrad Carlen</a>, <a class="external" href="mailto:do>netscape.com">Conrad Carlen</a>, <a class="link-mailto" href="mai
>ugt@netscape.com">Doug Turner</a>>lto:dougt@netscape.com">Doug Turner</a>

Back to History