1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rdf/base/idl/nsIRDFService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,146 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +#include "nsIRDFResource.idl"
1.11 +#include "nsIRDFLiteral.idl"
1.12 +#include "nsIRDFDataSource.idl"
1.13 +
1.14 +
1.15 +/**
1.16 + * The RDF service interface. This is a singleton object which should be
1.17 + * obtained from the <code>nsServiceManager</code>.
1.18 + */
1.19 +[scriptable, uuid(BFD05261-834C-11d2-8EAC-00805F29F370)]
1.20 +interface nsIRDFService : nsISupports {
1.21 + /**
1.22 + * Construct an RDF resource from a single-byte URI. <code>nsIRDFService</code>
1.23 + * caches resources that are in-use, so multiple calls to <code>GetResource()</code>
1.24 + * for the same <code>uri</code> will return identical pointers. FindResource
1.25 + * is used to find out whether there already exists a resource corresponding to that url.
1.26 + */
1.27 + nsIRDFResource GetResource(in AUTF8String aURI);
1.28 +
1.29 + /**
1.30 + * Construct an RDF resource from a Unicode URI. This is provided
1.31 + * as a convenience method, allowing automatic, in-line C++
1.32 + * conversion from <code>nsString</code> objects. The <code>uri</code> will
1.33 + * be converted to a single-byte representation internally.
1.34 + */
1.35 + nsIRDFResource GetUnicodeResource(in AString aURI);
1.36 +
1.37 + nsIRDFResource GetAnonymousResource();
1.38 +
1.39 + /**
1.40 + * Construct an RDF literal from a Unicode string.
1.41 + */
1.42 + nsIRDFLiteral GetLiteral(in wstring aValue);
1.43 +
1.44 + /**
1.45 + * Construct an RDF literal from a PRTime.
1.46 + */
1.47 + nsIRDFDate GetDateLiteral(in PRTime aValue);
1.48 +
1.49 + /**
1.50 + * Construct an RDF literal from an int.
1.51 + */
1.52 + nsIRDFInt GetIntLiteral(in long aValue);
1.53 +
1.54 + /**
1.55 + * Construct an RDF literal from a data blob
1.56 + */
1.57 + [noscript] nsIRDFBlob getBlobLiteral(in const_octet_ptr aValue, in long aLength);
1.58 +
1.59 + boolean IsAnonymousResource(in nsIRDFResource aResource);
1.60 +
1.61 + /**
1.62 + * Registers a resource with the RDF system, making it unique w.r.t.
1.63 + * GetResource.
1.64 + *
1.65 + * An implementation of nsIRDFResource should call this in its
1.66 + * Init() method if it wishes the resource to be globally unique
1.67 + * (which is usually the case).
1.68 + *
1.69 + * @note that the resource will <i>not</i> be ref-counted by the
1.70 + * RDF service: the assumption is that the resource implementation
1.71 + * will call nsIRDFService::UnregisterResource() when the last
1.72 + * reference to the resource is released.
1.73 + *
1.74 + * @note that the nsIRDFService implementation may choose to
1.75 + * maintain a reference to the resource's URI; therefore, the
1.76 + * resource implementation should ensure that the resource's URI
1.77 + * (accessible via nsIRDFResource::GetValue(const char* *aURI)) is
1.78 + * valid before calling RegisterResource(). Furthermore, the
1.79 + * resource implementation should ensure that this pointer
1.80 + * <i>remains</i> valid for the lifetime of the resource. (The
1.81 + * implementation of the resource cache in nsIRDFService uses the
1.82 + * URI maintained "internally" in the resource as a key into the
1.83 + * cache rather than copying the resource URI itself.)
1.84 + */
1.85 + void RegisterResource(in nsIRDFResource aResource, in boolean aReplace);
1.86 +
1.87 + /**
1.88 + * Called to notify the resource manager that a resource is no
1.89 + * longer in use. This method should only be called from the
1.90 + * destructor of a "custom" resource implementation to notify the
1.91 + * RDF service that the last reference to the resource has been
1.92 + * released, so the resource is no longer valid.
1.93 + *
1.94 + * @note As mentioned in nsIRDFResourceFactory::CreateResource(),
1.95 + * the RDF service will use the result of
1.96 + * nsIRDFResource::GetValue() as a key into its cache. For this
1.97 + * reason, you must always un-cache the resource <b>before</b>
1.98 + * releasing the storage for the <code>const char*</code> URI.
1.99 + */
1.100 + void UnregisterResource(in nsIRDFResource aResource);
1.101 +
1.102 + /**
1.103 + * Register a <i>named data source</i>. The RDF service will call
1.104 + * <code>nsIRDFDataSource::GetURI()</code> to determine the URI under
1.105 + * which to register the data source.
1.106 + *
1.107 + * @note that the data source will <i>not</i> be refcounted by the
1.108 + * RDF service! The assumption is that an RDF data source
1.109 + * registers with the service once it is initialized (via
1.110 + * <code>nsIRDFDataSource::Init()</code>), and unregisters when the
1.111 + * last reference to the data source is released.
1.112 + */
1.113 + void RegisterDataSource(in nsIRDFDataSource aDataSource,
1.114 + in boolean aReplace);
1.115 +
1.116 + /**
1.117 + * Unregister a <i>named data source</i>. The RDF service will call
1.118 + * <code>nsIRDFDataSource::GetURI()</code> to determine the URI under which the
1.119 + * data source was registered.
1.120 + */
1.121 + void UnregisterDataSource(in nsIRDFDataSource aDataSource);
1.122 +
1.123 + /**
1.124 + * Get the <i>named data source</i> corresponding to the URI. If a data
1.125 + * source has been registered via <code>RegisterDataSource()</code>, that
1.126 + * data source will be returned.
1.127 + *
1.128 + * If no data source is currently
1.129 + * registered for the specified URI, and a data source <i>constructor</i>
1.130 + * function has been registered via <code>RegisterDatasourceConstructor()</code>,
1.131 + * the RDF service will call the constructor to attempt to construct a
1.132 + * new data source. If construction is successful, the data source will
1.133 + * be initialized via <code>nsIRDFDataSource::Init()</code>.
1.134 + */
1.135 + nsIRDFDataSource GetDataSource(in string aURI);
1.136 +
1.137 + /**
1.138 + * Same as GetDataSource, but if a remote/XML data source needs to be
1.139 + * constructed, then this method will issue a <b>blocking</b> Refresh
1.140 + * call on that data source.
1.141 + */
1.142 + nsIRDFDataSource GetDataSourceBlocking(in string aURI);
1.143 +};
1.144 +
1.145 +%{C++
1.146 +extern nsresult
1.147 +NS_NewRDFService(nsIRDFService** result);
1.148 +%}
1.149 +
