148
edits
NPAPI:ClearSiteData: Difference between revisions
→Definition of domain
| (14 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
= Status = | = Status = | ||
Accepted, ready for implementation. | |||
= Contributors = | = Contributors = | ||
* Last modified: | * Last modified: January 6, 2011 | ||
* Authors: Julian Reschke (greenbytes), Dan Witte (Mozilla), Bernhard Bauer (Chromium), Rajesh Gwalani (Adobe), Josh Aas (Mozilla) | * Authors: Julian Reschke (greenbytes), Dan Witte (Mozilla), Bernhard Bauer (Chromium), Rajesh Gwalani (Adobe), Josh Aas (Mozilla), Maciej Stachowiak (Apple) | ||
= Overview = | = Overview = | ||
Allows browsers to | Allows browsers to discover and clear plugin private data. | ||
= Specification = | = Specification = | ||
== Definition of domain == | |||
The return value of NPP_GetSitesWithData and the 'site' argument to NPP_ClearSiteData must be domains only (not complete URIs or IRIs). For ASCII domains, they must be lowercase; in the case of internationalized domains, they must be NFKC-encoded (normalized) UTF-8. No other encoding is allowed. IP address literals must be enclosed in square brackets '[]'. This is in accordance with RFC 3987, Internationalized Resource Identifiers (IRIs). | |||
== Discovering Data == | |||
The following method will allow browsers to discover which sites a plugin has data for. Note that plugins (but no instances) must be initialized and function tables retrieved in order to call this method. | |||
<pre> | |||
char** NPP_GetSitesWithData(void); | |||
</pre> | |||
This function returns a <code>NULL</code>-terminated list of sites with data. Each site string is a domain as specified above under 'Definition of domain'. Memory for the array and the site strings must be allocated with <code>NPN_MemAlloc</code> and the browser will be responsible for freeing the memory with <code>NPN_MemFree</code>. | |||
== Clearing Data == | |||
The following method will allow browsers to request that plugins clear data. Note that plugins (but no instances) must be initialized and function tables retrieved in order to call this method. | The following method will allow browsers to request that plugins clear data. Note that plugins (but no instances) must be initialized and function tables retrieved in order to call this method. | ||
| Line 18: | Line 34: | ||
<pre> | <pre> | ||
NPError NPP_ClearSiteData( | NPError NPP_ClearSiteData( | ||
const char* site, // site for which to clear data | const char* site, // site for which to clear data | ||
uint64_t flags, // what type of data to clear | |||
uint64_t maxAge // max. age of information in seconds | |||
); | ); | ||
</pre> | </pre> | ||
* The <code>site</code> argument is interpreted as follows: | |||
** If <code>NULL</code>, all site-specific data and more generic data on browsing history (for instance, number of sites visited) should be cleared. | |||
** If <code>!NULL</code>, argument is a site string from the discovery API (an exact copy or the original). See above under 'Definition of domain' for the required form of the string. The browser is responsible for allocating and freeing the memory used for this argument. The plugin must copy the string in order to retain it outside the scope of the call. | |||
* The <code>flags</code> argument is a bit mask representing the type(s) of data to clear. | * The <code>flags</code> argument is a bit mask representing the type(s) of data to clear. | ||
<pre> | <pre> | ||
/* | #define NP_CLEAR_ALL 0 /* Clear all private data */ | ||
#define | #define NP_CLEAR_CACHE 1 << 0 /* Clear cached data which can simply be | ||
retrieved again as requested. To be used | |||
/* | out of concern for space and not necessarily | ||
privacy. */ | |||
/* More flags may be defined later, this spec will be updated. */ | /* More flags may be defined later, this spec will be updated. */ | ||
</pre> | </pre> | ||
* The <code>maxAge</code> argument is the maximum age in seconds of data to clear, inclusive. If <code>maxAge</code> is <code>0</code>, no data is cleared. If <code>maxAge</code> is the maximum unsigned 64-bit integer, all data is cleared. | * The <code>maxAge</code> argument is the maximum age in seconds of data to clear, inclusive. If <code>maxAge</code> is <code>0</code>, no data is cleared. If <code>maxAge</code> is the maximum unsigned 64-bit integer, all data is cleared. | ||
The following new NPError values will be available for return from <code>NPP_ClearSiteData</code> | The following new <code>NPError</code> values will be available for return from <code>NPP_ClearSiteData</code>: | ||
<pre> | <pre> | ||
// can't clear by time range | // can't clear by time range | ||
#define | #define NPERR_TIME_RANGE_NOT_SUPPORTED (NPERR_BASE + 14) | ||
// malformed 'site' string | |||
#define NPERR_MALFORMED_SITE (NPERR_BASE + 15) | |||
// malformed ' | |||
#define | |||
</pre> | </pre> | ||
| Line 54: | Line 66: | ||
If site data is in use by an instance of the plugin when <code>NPP_ClearSiteData</code> is called then it is up to the plugin to do the right thing. | If site data is in use by an instance of the plugin when <code>NPP_ClearSiteData</code> is called then it is up to the plugin to do the right thing. | ||
= Notes = | = Notes = | ||
Notes for this specification are [[NPAPI:ClearPrivateDataNotes|here]]. | |||