rdf/base/idl/nsIRDFService.idl@b8a032363ba2 (annotated)
rdf/base/idl/nsIRDFService.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | #include "nsISupports.idl" |
| michael@0 | 7 | #include "nsIRDFResource.idl" |
| michael@0 | 8 | #include "nsIRDFLiteral.idl" |
| michael@0 | 9 | #include "nsIRDFDataSource.idl" |
| michael@0 | 10 | |
| michael@0 | 11 | |
| michael@0 | 12 | /** |
| michael@0 | 13 | * The RDF service interface. This is a singleton object which should be |
| michael@0 | 14 | * obtained from the <code>nsServiceManager</code>. |
| michael@0 | 15 | */ |
| michael@0 | 16 | [scriptable, uuid(BFD05261-834C-11d2-8EAC-00805F29F370)] |
| michael@0 | 17 | interface nsIRDFService : nsISupports { |
| michael@0 | 18 | /** |
| michael@0 | 19 | * Construct an RDF resource from a single-byte URI. <code>nsIRDFService</code> |
| michael@0 | 20 | * caches resources that are in-use, so multiple calls to <code>GetResource()</code> |
| michael@0 | 21 | * for the same <code>uri</code> will return identical pointers. FindResource |
| michael@0 | 22 | * is used to find out whether there already exists a resource corresponding to that url. |
| michael@0 | 23 | */ |
| michael@0 | 24 | nsIRDFResource GetResource(in AUTF8String aURI); |
| michael@0 | 25 | |
| michael@0 | 26 | /** |
| michael@0 | 27 | * Construct an RDF resource from a Unicode URI. This is provided |
| michael@0 | 28 | * as a convenience method, allowing automatic, in-line C++ |
| michael@0 | 29 | * conversion from <code>nsString</code> objects. The <code>uri</code> will |
| michael@0 | 30 | * be converted to a single-byte representation internally. |
| michael@0 | 31 | */ |
| michael@0 | 32 | nsIRDFResource GetUnicodeResource(in AString aURI); |
| michael@0 | 33 | |
| michael@0 | 34 | nsIRDFResource GetAnonymousResource(); |
| michael@0 | 35 | |
| michael@0 | 36 | /** |
| michael@0 | 37 | * Construct an RDF literal from a Unicode string. |
| michael@0 | 38 | */ |
| michael@0 | 39 | nsIRDFLiteral GetLiteral(in wstring aValue); |
| michael@0 | 40 | |
| michael@0 | 41 | /** |
| michael@0 | 42 | * Construct an RDF literal from a PRTime. |
| michael@0 | 43 | */ |
| michael@0 | 44 | nsIRDFDate GetDateLiteral(in PRTime aValue); |
| michael@0 | 45 | |
| michael@0 | 46 | /** |
| michael@0 | 47 | * Construct an RDF literal from an int. |
| michael@0 | 48 | */ |
| michael@0 | 49 | nsIRDFInt GetIntLiteral(in long aValue); |
| michael@0 | 50 | |
| michael@0 | 51 | /** |
| michael@0 | 52 | * Construct an RDF literal from a data blob |
| michael@0 | 53 | */ |
| michael@0 | 54 | [noscript] nsIRDFBlob getBlobLiteral(in const_octet_ptr aValue, in long aLength); |
| michael@0 | 55 | |
| michael@0 | 56 | boolean IsAnonymousResource(in nsIRDFResource aResource); |
| michael@0 | 57 | |
| michael@0 | 58 | /** |
| michael@0 | 59 | * Registers a resource with the RDF system, making it unique w.r.t. |
| michael@0 | 60 | * GetResource. |
| michael@0 | 61 | * |
| michael@0 | 62 | * An implementation of nsIRDFResource should call this in its |
| michael@0 | 63 | * Init() method if it wishes the resource to be globally unique |
| michael@0 | 64 | * (which is usually the case). |
| michael@0 | 65 | * |
| michael@0 | 66 | * @note that the resource will <i>not</i> be ref-counted by the |
| michael@0 | 67 | * RDF service: the assumption is that the resource implementation |
| michael@0 | 68 | * will call nsIRDFService::UnregisterResource() when the last |
| michael@0 | 69 | * reference to the resource is released. |
| michael@0 | 70 | * |
| michael@0 | 71 | * @note that the nsIRDFService implementation may choose to |
| michael@0 | 72 | * maintain a reference to the resource's URI; therefore, the |
| michael@0 | 73 | * resource implementation should ensure that the resource's URI |
| michael@0 | 74 | * (accessible via nsIRDFResource::GetValue(const char* *aURI)) is |
| michael@0 | 75 | * valid before calling RegisterResource(). Furthermore, the |
| michael@0 | 76 | * resource implementation should ensure that this pointer |
| michael@0 | 77 | * <i>remains</i> valid for the lifetime of the resource. (The |
| michael@0 | 78 | * implementation of the resource cache in nsIRDFService uses the |
| michael@0 | 79 | * URI maintained "internally" in the resource as a key into the |
| michael@0 | 80 | * cache rather than copying the resource URI itself.) |
| michael@0 | 81 | */ |
| michael@0 | 82 | void RegisterResource(in nsIRDFResource aResource, in boolean aReplace); |
| michael@0 | 83 | |
| michael@0 | 84 | /** |
| michael@0 | 85 | * Called to notify the resource manager that a resource is no |
| michael@0 | 86 | * longer in use. This method should only be called from the |
| michael@0 | 87 | * destructor of a "custom" resource implementation to notify the |
| michael@0 | 88 | * RDF service that the last reference to the resource has been |
| michael@0 | 89 | * released, so the resource is no longer valid. |
| michael@0 | 90 | * |
| michael@0 | 91 | * @note As mentioned in nsIRDFResourceFactory::CreateResource(), |
| michael@0 | 92 | * the RDF service will use the result of |
| michael@0 | 93 | * nsIRDFResource::GetValue() as a key into its cache. For this |
| michael@0 | 94 | * reason, you must always un-cache the resource <b>before</b> |
| michael@0 | 95 | * releasing the storage for the <code>const char*</code> URI. |
| michael@0 | 96 | */ |
| michael@0 | 97 | void UnregisterResource(in nsIRDFResource aResource); |
| michael@0 | 98 | |
| michael@0 | 99 | /** |
| michael@0 | 100 | * Register a <i>named data source</i>. The RDF service will call |
| michael@0 | 101 | * <code>nsIRDFDataSource::GetURI()</code> to determine the URI under |
| michael@0 | 102 | * which to register the data source. |
| michael@0 | 103 | * |
| michael@0 | 104 | * @note that the data source will <i>not</i> be refcounted by the |
| michael@0 | 105 | * RDF service! The assumption is that an RDF data source |
| michael@0 | 106 | * registers with the service once it is initialized (via |
| michael@0 | 107 | * <code>nsIRDFDataSource::Init()</code>), and unregisters when the |
| michael@0 | 108 | * last reference to the data source is released. |
| michael@0 | 109 | */ |
| michael@0 | 110 | void RegisterDataSource(in nsIRDFDataSource aDataSource, |
| michael@0 | 111 | in boolean aReplace); |
| michael@0 | 112 | |
| michael@0 | 113 | /** |
| michael@0 | 114 | * Unregister a <i>named data source</i>. The RDF service will call |
| michael@0 | 115 | * <code>nsIRDFDataSource::GetURI()</code> to determine the URI under which the |
| michael@0 | 116 | * data source was registered. |
| michael@0 | 117 | */ |
| michael@0 | 118 | void UnregisterDataSource(in nsIRDFDataSource aDataSource); |
| michael@0 | 119 | |
| michael@0 | 120 | /** |
| michael@0 | 121 | * Get the <i>named data source</i> corresponding to the URI. If a data |
| michael@0 | 122 | * source has been registered via <code>RegisterDataSource()</code>, that |
| michael@0 | 123 | * data source will be returned. |
| michael@0 | 124 | * |
| michael@0 | 125 | * If no data source is currently |
| michael@0 | 126 | * registered for the specified URI, and a data source <i>constructor</i> |
| michael@0 | 127 | * function has been registered via <code>RegisterDatasourceConstructor()</code>, |
| michael@0 | 128 | * the RDF service will call the constructor to attempt to construct a |
| michael@0 | 129 | * new data source. If construction is successful, the data source will |
| michael@0 | 130 | * be initialized via <code>nsIRDFDataSource::Init()</code>. |
| michael@0 | 131 | */ |
| michael@0 | 132 | nsIRDFDataSource GetDataSource(in string aURI); |
| michael@0 | 133 | |
| michael@0 | 134 | /** |
| michael@0 | 135 | * Same as GetDataSource, but if a remote/XML data source needs to be |
| michael@0 | 136 | * constructed, then this method will issue a <b>blocking</b> Refresh |
| michael@0 | 137 | * call on that data source. |
| michael@0 | 138 | */ |
| michael@0 | 139 | nsIRDFDataSource GetDataSourceBlocking(in string aURI); |
| michael@0 | 140 | }; |
| michael@0 | 141 | |
| michael@0 | 142 | %{C++ |
| michael@0 | 143 | extern nsresult |
| michael@0 | 144 | NS_NewRDFService(nsIRDFService** result); |
| michael@0 | 145 | %} |
| michael@0 | 146 |
