tubestation/toolkit/components/contentanalysis/nsIContentAnalysis.idl

/* -*- Mode: C++; c-basic-offset: 2; indent-tabs-mode: nil; tab-width: 8 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

webidl WindowGlobalParent;

[scriptable, uuid(06e6a60f-3a2b-41fa-a63b-fea7a7f71649)]
interface nsIContentAnalysisAcknowledgement : nsISupports
{
  // These values must stay synchronized with ContentAnalysisAcknowledgement
  // in analysis.proto!
  // Acknowledgement of analysis response.
  // The response was handled as specified by the agent.
  const unsigned long SUCCESS = 1;
  // The response from the agent was not properly formatted.
  const unsigned long INVALID_RESPONSE = 2;
  // The response from the agent was too late.
  const unsigned long TOO_LATE = 3;

  readonly attribute unsigned long result;

  // These values must stay synchronized with ContentAnalysisAcknowledgement
  // in analysis.proto!
  const unsigned long ACTION_UNSPECIFIED = 0;
  const unsigned long ALLOW = 1;
  const unsigned long REPORT_ONLY = 2;
  const unsigned long WARN = 3;
  const unsigned long BLOCK = 4;

  readonly attribute unsigned long finalAction;
};

[scriptable, builtinclass, uuid(89088c61-15f6-4ace-a880-a1b5ea47ca66)]
interface nsIContentAnalysisResponse : nsISupports
{
  // These values must stay synchronized with ContentAnalysisResponse
  // in analysis.proto!
  // Action requested in response to a successful analysis.
  const unsigned long ACTION_UNSPECIFIED = 0;
  const unsigned long REPORT_ONLY = 1;
  const unsigned long WARN = 2;
  const unsigned long BLOCK = 3;

  // Values that do not appear in analysis.proto
  const unsigned long ALLOW = 1000;

  [infallible] readonly attribute unsigned long action;
  [infallible] readonly attribute boolean shouldAllowContent;

  // Identifier for the corresponding nsIContentAnalysisRequest
  readonly attribute ACString requestToken;

  /**
   * Acknowledge receipt of an analysis response.
   * Should always be called after successful resolution of the promise
   * from AnalyzeContentRequest.
   */
  void acknowledge(in nsIContentAnalysisAcknowledgement aCaa);
};

[scriptable, uuid(48d31df1-204d-42ce-a57f-f156bb870d89)]
interface nsIClientDownloadResource : nsISupports
{
  readonly attribute AString url;

  // These values must stay synchronized with ClientDownloadResource
  // in analysis.proto!
  // The final URL of the download payload.  The resource URL should
  // correspond to the URL field above.
  const unsigned long DOWNLOAD_URL = 0;
  // A redirect URL that was fetched before hitting the final DOWNLOAD_URL.
  const unsigned long DOWNLOAD_REDIRECT = 1;
  // The final top-level URL of the tab that triggered the download.
  const unsigned long TAB_URL = 2;
  // A redirect URL thas was fetched before hitting the final TAB_URL.
  const unsigned long TAB_REDIRECT = 3;
  // The document URL for a PPAPI plugin instance that initiated the download.
  // This is the document.url for the container element for the plugin
  // instance.
  const unsigned long PPAPI_DOCUMENT = 4;
  // The plugin URL for a PPAPI plugin instance that initiated the download.
  const unsigned long PPAPI_PLUGIN = 5;

  readonly attribute unsigned long type;
};

/**
 * A nsIContentAnalysisRequest represents a request that the browser
 * consult any required content analysis resources (like external data-loss
 * prevention applications) to determine if the attempted operation should
 * be permitted to complete.
 */
[scriptable, uuid(c11a6636-da2a-4afc-bdd1-0bcae2310e6d)]
interface nsIContentAnalysisRequest : nsISupports
{
  // These values must stay synchronized with ContentAnalysisRequest
  // in analysis.proto!
  // Type of analysis being requested.
  // For meaning, see analysis.proto in the content analysis module.
  const unsigned long ANALYSIS_CONNECTOR_UNSPECIFIED = 0;
  const unsigned long FILE_DOWNLOADED = 1;
  const unsigned long FILE_ATTACHED = 2;
  const unsigned long BULK_DATA_ENTRY = 3;
  const unsigned long PRINT = 4;
  const unsigned long FILE_TRANSFER = 5;

  readonly attribute unsigned long analysisType;

  // Enumeration of what operation is happening, to be displayed to the user
  const unsigned long OPERATION_CUSTOMDISPLAYSTRING = 0;
  const unsigned long OPERATION_CLIPBOARD = 1;
  const unsigned long OPERATION_DROPPEDTEXT = 2;
  readonly attribute unsigned long operationTypeForDisplay;
  readonly attribute AString operationDisplayString;

  // Text content to analyze.  Only one of textContent or filePath is defined.
  readonly attribute AString textContent;

  // Name of file to analyze.  Only one of textContent or filePath is defined.
  readonly attribute AString filePath;

  // The URL containing the file download/upload or to which web content is
  // being uploaded.
  readonly attribute AString url;

  // Sha256 digest of file.
  readonly attribute ACString sha256Digest;

  // URLs involved in the download (empty for non-downloads).
  readonly attribute Array<nsIClientDownloadResource> resources;

  // Email address of user.
  readonly attribute AString email;

  // Unique identifier for this request
  readonly attribute ACString requestToken;

  // The window associated with this request
  readonly attribute WindowGlobalParent windowGlobalParent;
};

[scriptable, builtinclass, uuid(9679545f-4256-4c90-9654-90292c355d25)]
interface nsIContentAnalysisResult : nsISupports
{
  [infallible] readonly attribute boolean shouldAllowContent;
};

[scriptable, uuid(cb09fc88-118c-411b-aa89-2e1bc5e3eba6)]
interface nsIContentAnalysisCallback : nsISupports
{
  void contentResult(in nsIContentAnalysisResponse aResult);

  void error(in nsresult aResult);
};

[scriptable, builtinclass, uuid(61497587-2bba-4a88-acd3-3fbb2cedf163)]
interface nsIContentAnalysis : nsISupports
{
  /**
   * True if content analysis should be consulted.
   */
  readonly attribute bool isActive;

  /**
   * True if content analysis might be active, and False if content analysis
   * is definitely not active. Reading this property is guaranteed
   * to work from a content process, and can be used to avoid having to call
   * into the parent process to determine whether content analysis is actually
   * active.
   */
  readonly attribute bool mightBeActive;

  /**
   * Consults content analysis server, if any, to request a permission
   * decision for a network operation.  Allows blocking downloading/
   * uploading/printing/etc, based on the request.
   * Consultation with the content analysis tool follows the conventional
   * request, response, acknowledgement protocol.
   *
   * The resulting Promise resolves to a nsIContentAnalysisResponse,
   * which may take some time to get from the analysis server.  It will
   * be rejected, with an string error description, if any error occurs.
   * A successful nsIContentAnalysisResponse must be acknowledged.
   * See @nsIContentAnalysisResponse.
   */
  [implicit_jscontext]
  Promise analyzeContentRequest(in nsIContentAnalysisRequest aCar);

  /**
   * Same functionality as AnalyzeContentRequest(), but more convenient to call
   * from C++ since it takes a callback instead of returning a Promise.
   */
  void analyzeContentRequestCallback(in nsIContentAnalysisRequest aCar, in nsIContentAnalysisCallback callback);
};