chrome/common/extensions/api/autofill_private.idl

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.autofillPrivate</code> API to add, remove, or update
   6 // autofill data from the settings UI.
   7 namespace autofillPrivate {
   8   // Fields used as part of an address.
   9   enum AddressField {
  10     FULL_NAME,
  11     COMPANY_NAME,
  12     ADDRESS_LINES,
  13     ADDRESS_LEVEL_1,
  14     ADDRESS_LEVEL_2,
  15     ADDRESS_LEVEL_3,
  16     POSTAL_CODE,
  17     SORTING_CODE,
  18     COUNTRY_CODE
  19   };
  20
  21   // Metadata about an autofill entry (address or credit card) which is used to
  22   // render a summary list of all entries.
  23   dictionary AutofillMetadata {
  24     // Short summary of the address which is displayed in the UI; an
  25     // undefined value means that this entry has just been created on the client
  26     // and has not yet been given a summary.
  27     DOMString summaryLabel;
  28
  29     // Short, secondary summary of the address which is displalyed in the UI; an
  30     // undefined value means that this entry has just been created on the client
  31     // and has not yet been given a summary.
  32     DOMString? summarySublabel;
  33
  34     // Whether the entry is locally owned by Chrome (as opposed to being a
  35     // profile synced down from the server). Non-local entries may not be
  36     // editable.
  37     boolean? isLocal;
  38
  39     // For credit cards, whether this is a full copy of the card
  40     boolean? isCached;
  41   };
  42
  43   // An address entry which can be saved in the autofill section of the
  44   // settings UI.
  45   dictionary AddressEntry {
  46     // Globally unique identifier for this entry.
  47     DOMString? guid;
  48
  49     DOMString[]? fullNames;
  50
  51     DOMString? companyName;
  52
  53     // Street address (multiple lines, newlines preserved).
  54     DOMString? addressLines;
  55
  56     // The broadest administrative level in the address, i.e. the province
  57     // within which the locality is found; for example, in the US, this would be
  58     // the state; in Switzerland it would be the canton; in the UK, the post
  59     // town.
  60     DOMString? addressLevel1;
  61
  62     // The second administrative level, in addresses with two or more
  63     // administrative levels; in the countries with two administrative levels,
  64     // this would typically be the city, town, village, or other locality within
  65     // which the relevant street address is found.
  66     DOMString? addressLevel2;
  67
  68     // The third administrative level, in addresses with three or more
  69     // administrative levels.
  70     DOMString? addressLevel3;
  71
  72     // Postal code, post code, ZIP code, CEDEX code (if CEDEX, append "CEDEX",
  73     // and the arrondissement, if relevant, to the address-level2 field).
  74     DOMString? postalCode;
  75
  76     // A sorting code is similar to a postal code. However, whereas a postal
  77     // code normally refers to a single geographical location, a sorting code
  78     // often does not. Instead, a sorting code is assigned to an organization,
  79     // which might be geographically distributed. The most prominent example of
  80     // a sorting code system is CEDEX in France.
  81     DOMString? sortingCode;
  82
  83     // A two-character string representing the address' country. See
  84     // autofill_country.cc for a list of valid codes.
  85     DOMString? countryCode;
  86
  87     DOMString[]? phoneNumbers;
  88
  89     DOMString[]? emailAddresses;
  90
  91     DOMString? languageCode;
  92
  93     AutofillMetadata? metadata;
  94   };
  95
  96   // A component to be shown in an address editor. Different countries have
  97   // different components to their addresses.
  98   dictionary AddressComponent {
  99     // The field type.
 100     AddressField field;
 101
 102     // The name of the field.
 103     DOMString fieldName;
 104
 105     // A hint for the UI regarding whether the input is likely to be long.
 106     boolean isLongField;
 107
 108     // A placeholder for the text field to be used when the user has not yet
 109     // input a value for the field.
 110     DOMString? placeholder;
 111   };
 112
 113   // A row of address components. Each component in a row should be shown in the
 114   // same row in the UI. For example, city, state, and zip code are all included
 115   // on the same line for US addresses.
 116   dictionary AddressComponentRow {
 117     AddressComponent[] row;
 118   };
 119
 120   // The address components for a given country code. Each entry in |components|
 121   // constitutes a row in the UI, while each inner array contains the list of
 122   // components to use in that row. For example, city, state, and zip code are
 123   // all included on the same line for US addresses. This dictionary also
 124   // includes the associated language code.
 125   dictionary AddressComponents {
 126     // The components.
 127     AddressComponentRow[] components;
 128
 129     // The language code.
 130     DOMString languageCode;
 131   };
 132
 133   // A credit card entry which can be saved in the autofill section of the
 134   // settings UI.
 135   dictionary CreditCardEntry {
 136     // Globally unique identifier for this entry.
 137     DOMString? guid;
 138
 139     // Name of the person who owns the credit card.
 140     DOMString? name;
 141
 142     // Credit card number.
 143     DOMString? cardNumber;
 144
 145     // Month as 2-character string ("01" = January, "12" = December).
 146     DOMString? expirationMonth;
 147
 148     // Year as a 4-character string (as in "2015").
 149     DOMString? expirationYear;
 150
 151     AutofillMetadata? metadata;
 152   };
 153
 154   // Parameters to be passed to validatePhoneNumbers().
 155   dictionary ValidatePhoneParams {
 156     // The phone numbers to validate.
 157     DOMString[] phoneNumbers;
 158
 159     // The index into |phoneNumbers| at which the newly-added/edited phone
 160     // number resides.
 161     long indexOfNewNumber;
 162
 163     // A two-character string representing the address' country. See
 164     // autofill_country.cc for a list of valid codes.
 165     DOMString countryCode;
 166   };
 167
 168   callback GetAddressComponentsCallback =
 169       void(AddressComponents components);
 170   callback ValidatePhoneNumbersCallback =
 171       void(DOMString[] validatedPhoneNumbers);
 172
 173   interface Functions {
 174     // Saves the given address. If |address| has an empty string as its ID, it
 175     // will be assigned a new one and added as a new entry.
 176     //
 177     // |address|: The address entry to save.
 178     static void saveAddress(AddressEntry address);
 179
 180     // Gets the address components for a given country code.
 181     //
 182     // |countryCode|: A two-character string representing the address' country
 183     //     whose components should be returned. See autofill_country.cc for a
 184     //     list of valid codes.
 185     // |callback|: Callback which will be called with components.
 186     static void getAddressComponents(DOMString countryCode,
 187         GetAddressComponentsCallback callback);
 188
 189     // Saves the given credit card. If |card| has an empty string as its
 190     // ID, it will be assigned a new one and added as a new entry.
 191     //
 192     // |card|: The card entry to save.
 193     static void saveCreditCard(CreditCardEntry card);
 194
 195     // Removes the entry (address or credit card) with the given ID.
 196     //
 197     // |guid|: ID of the entry to remove.
 198     static void removeEntry(DOMString guid);
 199
 200     // Validates a newly-added phone number and invokes the callback with a list
 201     // of validated numbers. Note that if the newly-added number was invalid, it
 202     // will not be returned in the list of valid numbers.
 203     //
 204     // |params|: The parameters to this function.
 205     // |callback|: Callback which will be called with validated phone numbers.
 206     static void validatePhoneNumbers(ValidatePhoneParams params,
 207         ValidatePhoneNumbersCallback callback);
 208
 209     // Clears the data associated with a wallet card which was saved
 210     // locally so that the saved copy is masked (e.g., "Card ending
 211     // in 1234").
 212     //
 213     // |guid|: GUID of the credit card to mask.
 214     static void maskCreditCard(DOMString guid);
 215   };
 216
 217   interface Events {
 218     // Fired when the address list has changed, meaning that an entry has been
 219     // added, removed, or changed.
 220     //
 221     // |entries| The updated list of entries.
 222     static void onAddressListChanged(AddressEntry[] entries);
 223
 224     // Fired when the credit card list has changed, meaning that an entry has
 225     // been added, removed, or changed.
 226     //
 227     // |entries| The updated list of entries.
 228     static void onCreditCardListChanged(CreditCardEntry[] entries);
 229   };
 230 };