1<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note: 2 1) The <head> information in this page is significant, should be uniform 3 across api docs and should be edited only with knowledge of the 4 templating mechanism. 5 3) All <body>.innerHTML is genereated as an rendering step. If viewed in a 6 browser, it will be re-generated from the template, json schema and 7 authored overview content. 8 4) The <body>.innerHTML is also generated by an offline step so that this 9 page may easily be indexed by search engines. 10--><html xmlns="http://www.w3.org/1999/xhtml"><head> 11 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 12 <link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css"> 13 <link href="css/print.css" rel="stylesheet" type="text/css" media="print"> 14 <script type="text/javascript" src="/third_party/jstemplate/jstemplate_compiled.js"> 15 </script> 16 <script type="text/javascript" src="js/api_page_generator.js"></script> 17 <script type="text/javascript" src="js/bootstrap.js"></script> 18 <script type="text/javascript" src="js/sidebar.js"></script> 19 <title>Cross-Origin XMLHttpRequest - Google Chrome Extensions - Google Code</title></head> 20 <body> <div id="gc-container" class="labs"> 21 <div id="devModeWarning"> 22 You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files. 23 </div> 24 <!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION --> 25 <!-- In particular, sub-templates that recurse, must be used by allowing 26 jstemplate to make a copy of the template in this section which 27 are not operated on by way of the jsskip="true" --> 28 <div style="display:none"> 29 30 <!-- VALUE --> 31 <div id="valueTemplate"> 32 <dt> 33 <var>paramName</var> 34 <em> 35 36 <!-- TYPE --> 37 <div style="display:inline"> 38 ( 39 <span class="optional">optional</span> 40 <span class="enum">enumerated</span> 41 <span id="typeTemplate"> 42 <span> 43 <a> Type</a> 44 </span> 45 <span> 46 <span> 47 array of <span><span></span></span> 48 </span> 49 <span>paramType</span> 50 <span></span> 51 </span> 52 </span> 53 ) 54 </div> 55 56 </em> 57 </dt> 58 <dd class="todo"> 59 Undocumented. 60 </dd> 61 <dd> 62 Description of this parameter from the json schema. 63 </dd> 64 <dd> 65 This parameter was added in version 66 <b><span></span></b>. 67 You must omit this parameter in earlier versions, 68 and you may omit it in any version. If you require this 69 parameter, the manifest key 70 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 71 can ensure that your extension won't be run in an earlier browser version. 72 </dd> 73 74 <!-- OBJECT PROPERTIES --> 75 <dd> 76 <dl> 77 <div> 78 <div> 79 </div> 80 </div> 81 </dl> 82 </dd> 83 84 <!-- OBJECT METHODS --> 85 <dd> 86 <div></div> 87 </dd> 88 89 <!-- OBJECT EVENT FIELDS --> 90 <dd> 91 <div></div> 92 </dd> 93 94 <!-- FUNCTION PARAMETERS --> 95 <dd> 96 <div></div> 97 </dd> 98 99 </div> <!-- /VALUE --> 100 101 <div id="functionParametersTemplate"> 102 <h5>Parameters</h5> 103 <dl> 104 <div> 105 <div> 106 </div> 107 </div> 108 </dl> 109 </div> 110 </div> <!-- /SUBTEMPLATES --> 111 112 <a id="top"></a> 113 <div id="skipto"> 114 <a href="#gc-pagecontent">Skip to page content</a> 115 <a href="#gc-toc">Skip to main navigation</a> 116 </div> 117 <!-- API HEADER --> 118 <table id="header" width="100%" cellspacing="0" border="0"> 119 <tbody><tr> 120 <td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td> 121 <td valign="middle" width="100%" style="padding-left:0.6em;"> 122 <form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em"> 123 <div id="gsc-search-box"> 124 <input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno"> 125 <input type="hidden" name="ie" value="UTF-8"> 126 <input type="text" name="q" value="" size="55"> 127 <input class="gsc-search-button" type="submit" name="sa" value="Search"> 128 <br> 129 <span class="greytext">e.g. "page action" or "tabs"</span> 130 </div> 131 </form> 132 133 <script type="text/javascript" src="http://www.google.com/jsapi"></script> 134 <script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script> 135 <script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script> 136 <script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script> 137 </td> 138 </tr> 139 </tbody></table> 140 141 <div id="codesiteContent" class=""> 142 143 <a id="gc-topnav-anchor"></a> 144 <div id="gc-topnav"> 145 <h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1> 146 <ul id="home" class="gc-topnav-tabs"> 147 <li id="home_link"> 148 <a href="index.html" title="Google Chrome Extensions home page">Home</a> 149 </li> 150 <li id="docs_link"> 151 <a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a> 152 </li> 153 <li id="faq_link"> 154 <a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a> 155 </li> 156 <li id="samples_link"> 157 <a href="samples.html" title="Sample extensions (with source code)">Samples</a> 158 </li> 159 <li id="group_link"> 160 <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a> 161 </li> 162 </ul> 163 </div> <!-- end gc-topnav --> 164 165 <div class="g-section g-tpl-170"> 166 <!-- SIDENAV --> 167 <div class="g-unit g-first" id="gc-toc"> 168 <ul> 169 <li><a href="getstarted.html">Getting Started</a></li> 170 <li><a href="overview.html">Overview</a></li> 171 <li><a href="whats_new.html">What's New?</a></li> 172 <li><h2><a href="devguide.html">Developer's Guide</a></h2> 173 <ul> 174 <li>Browser UI 175 <ul> 176 <li><a href="browserAction.html">Browser Actions</a></li> 177 <li><a href="contextMenus.html">Context Menus</a></li> 178 <li><a href="notifications.html">Desktop Notifications</a></li> 179 <li><a href="omnibox.html">Omnibox</a></li> 180 <li><a href="options.html">Options Pages</a></li> 181 <li><a href="override.html">Override Pages</a></li> 182 <li><a href="pageAction.html">Page Actions</a></li> 183 </ul> 184 </li> 185 <li>Browser Interaction 186 <ul> 187 <li><a href="bookmarks.html">Bookmarks</a></li> 188 <li><a href="cookies.html">Cookies</a></li> 189 <li><a href="events.html">Events</a></li> 190 <li><a href="history.html">History</a></li> 191 <li><a href="management.html">Management</a></li> 192 <li><a href="tabs.html">Tabs</a></li> 193 <li><a href="windows.html">Windows</a></li> 194 </ul> 195 </li> 196 <li>Implementation 197 <ul> 198 <li><a href="a11y.html">Accessibility</a></li> 199 <li><a href="background_pages.html">Background Pages</a></li> 200 <li><a href="content_scripts.html">Content Scripts</a></li> 201 <li class="leftNavSelected">Cross-Origin XHR</li> 202 <li><a href="idle.html">Idle</a></li> 203 <li><a href="i18n.html">Internationalization</a></li> 204 <li><a href="messaging.html">Message Passing</a></li> 205 <li><a href="npapi.html">NPAPI Plugins</a></li> 206 </ul> 207 </li> 208 <li>Finishing 209 <ul> 210 <li><a href="hosting.html">Hosting</a></li> 211 <li><a href="external_extensions.html">Other Deployment Options</a></li> 212 </ul> 213 </li> 214 </ul> 215 </li> 216 <li><h2><a href="apps.html">Packaged Apps</a></h2></li> 217 <li><h2><a href="tutorials.html">Tutorials</a></h2> 218 <ul> 219 <li><a href="tut_debugging.html">Debugging</a></li> 220 <li><a href="tut_analytics.html">Google Analytics</a></li> 221 <li><a href="tut_oauth.html">OAuth</a></li> 222 </ul> 223 </li> 224 <li><h2>Reference</h2> 225 <ul> 226 <li>Formats 227 <ul> 228 <li><a href="manifest.html">Manifest Files</a></li> 229 <li><a href="match_patterns.html">Match Patterns</a></li> 230 </ul> 231 </li> 232 <li><a href="permission_warnings.html">Permission Warnings</a></li> 233 <li><a href="api_index.html">chrome.* APIs</a></li> 234 <li><a href="api_other.html">Other APIs</a></li> 235 </ul> 236 </li> 237 <li><h2><a href="samples.html">Samples</a></h2></li> 238 <div class="line"> </div> 239 <li><h2>More</h2> 240 <ul> 241 <li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li> 242 <li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li> 243 <li><a href="themes.html">Themes</a></li> 244 </ul> 245 </li> 246 </ul> 247 </div> 248 <script> 249 initToggles(); 250 </script> 251 252 <div class="g-unit" id="gc-pagecontent"> 253 <div id="pageTitle"> 254 <h1 class="page_title">Cross-Origin XMLHttpRequest</h1> 255 </div> 256 <!-- TABLE OF CONTENTS --> 257 <div id="toc" style="display: none; "> 258 <h2>Contents</h2> 259 <ol> 260 <li> 261 <a>h2Name</a> 262 <ol> 263 <li> 264 <a>h3Name</a> 265 </li> 266 </ol> 267 </li> 268 <li> 269 <a href="#apiReference">API reference</a> 270 <ol> 271 <li> 272 <a href="#properties">Properties</a> 273 <ol> 274 <li> 275 <a href="#property-anchor">propertyName</a> 276 </li> 277 </ol> 278 </li> 279 <li> 280 <a>Methods</a> 281 <ol> 282 <li> 283 <a href="#method-anchor">methodName</a> 284 </li> 285 </ol> 286 </li> 287 <li> 288 <a>Events</a> 289 <ol> 290 <li> 291 <a href="#event-anchor">eventName</a> 292 </li> 293 </ol> 294 </li> 295 <li> 296 <a href="#types">Types</a> 297 <ol> 298 <li> 299 <a href="#id-anchor">id</a> 300 </li> 301 </ol> 302 </li> 303 </ol> 304 </li> 305 </ol> 306 </div> 307 <!-- /TABLE OF CONTENTS --> 308 309 <!-- Standard content lead-in for experimental API pages --> 310 <p id="classSummary" style="display: none; "> 311 For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page. 312 </p> 313 314 <!-- STATIC CONTENT PLACEHOLDER --> 315 <div id="static"><div id="pageData-name" class="pageData">Cross-Origin XMLHttpRequest</div> 316 317<!-- BEGIN AUTHORED CONTENT --> 318<p id="classSummary"> 319Regular web pages can use the 320<a href="http://www.w3.org/TR/XMLHttpRequest/">XMLHttpRequest</a> 321object to send and receive data from remote servers, 322but they're limited by the 323<a href="http://en.wikipedia.org/wiki/Same_origin_policy">same origin policy</a>. 324Extensions aren't so limited. 325An extension can talk to remote servers outside of its origin, 326as long as it first requests cross-origin permissions.</p> 327 328<p class="note"> 329<b>Note:</b> 330Content scripts can't directly make cross-origin requests. 331However, a content script can 332send a message to its parent extension 333that asks the extension to make a cross-origin request. 334For an example of this technique, see the 335<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/howto/contentscript_xhr">contentscript_xhr example</a>. 336</p> 337 338<h2 id="extension-origin">Extension origin</h2> 339<p>Each running extension exists within its own separate security origin. Without 340requesting additional privileges, the extension can use 341XMLHttpRequest to get resources within its installation. For example, if 342an extension contains a JSON configuration file called <code>config.json</code>, 343in a <code>config_resources</code> folder, the extension can retrieve the file's contents like 344this:</p> 345 346<pre>var xhr = new XMLHttpRequest(); 347xhr.onreadystatechange = handleStateChange; // Implemented elsewhere. 348xhr.open("GET", chrome.extension.getURL('/config_resources/config.json'), true); 349xhr.send(); 350</pre> 351 352<p>If the extension attempts to use a security origin other than itself, 353say http://www.google.com, 354the browser disallows it 355unless the extension has requested the appropriate cross-origin permissions. 356</p> 357 358<h2 id="requesting-permission">Requesting cross-origin permissions</h2> 359 360<p>By adding hosts or host match patterns (or both) to the 361<a href="manifest.html#permissions">permissions</a> section of the 362<a href="manifest.html">manifest</a> file, the extension can request access to 363remote servers outside of its origin.</p> 364 365<pre>{ 366 "name": "My extension", 367 ... 368 <b>"permissions": [ 369 "http://www.google.com/" 370 ]</b>, 371 ... 372}</pre> 373 374<p>Cross-origin permission values can be fully qualified host names, 375like these:</p> 376 377<ul> 378 <li> "http://www.google.com/" </li> 379 <li> "http://www.gmail.com/" </li> 380</ul> 381 382<p>Or they can be match patterns, like these:</p> 383 384<ul> 385 <li> "http://*.google.com/" </li> 386 <li> "http://*/" </li> 387</ul> 388 389<p> 390A match pattern of "http://*/" allows HTTP access to all reachable domains. 391Note that here, 392match patterns are similar to <a href="match_patterns.html">content script 393match patterns</a>, 394but any path information following the host is ignored.</p> 395 396<p>Also note that access is granted both by host and by scheme. If an extension 397wants both secure and non-secure HTTP access to a given host or set 398of hosts, it must declare the permissions separately:</p> 399 400<pre>"permissions": [ 401 "http://www.google.com/", 402 "https://www.google.com/" 403] 404</pre> 405 406<h2 id="security-considerations">Security considerations</h2> 407 408<p> 409When using resources retrieved via XMLHttpRequest, your background page should 410be careful not to fall victim to <a href="http://en.wikipedia.org/wiki/Cross-site_scripting">cross-site 411scripting</a>. Specifically, avoid using dangerous APIs such as the below: 412</p> 413<pre>background.html 414=============== 415var xhr = new XMLHttpRequest(); 416xhr.open("GET", "http://api.example.com/data.json", true); 417xhr.onreadystatechange = function() { 418 if (xhr.readyState == 4) { 419 // WARNING! Might be evaluating an evil script! 420 var resp = eval("(" + xhr.responseText + ")"); 421 ... 422 } 423} 424xhr.send(); 425 426background.html 427=============== 428var xhr = new XMLHttpRequest(); 429xhr.open("GET", "http://api.example.com/data.json", true); 430xhr.onreadystatechange = function() { 431 if (xhr.readyState == 4) { 432 // WARNING! Might be injecting a malicious script! 433 document.getElementById("resp").innerHTML = xhr.responseText; 434 ... 435 } 436} 437xhr.send(); 438</pre> 439<p> 440Instead, prefer safer APIs that do not run scripts: 441</p> 442<pre>background.html 443=============== 444var xhr = new XMLHttpRequest(); 445xhr.open("GET", "http://api.example.com/data.json", true); 446xhr.onreadystatechange = function() { 447 if (xhr.readyState == 4) { 448 // JSON.parse does not evaluate the attacker's scripts. 449 var resp = JSON.parse(xhr.responseText); 450 } 451} 452xhr.send(); 453 454background.html 455=============== 456var xhr = new XMLHttpRequest(); 457xhr.open("GET", "http://api.example.com/data.json", true); 458xhr.onreadystatechange = function() { 459 if (xhr.readyState == 4) { 460 // innerText does not let the attacker inject HTML elements. 461 document.getElementById("resp").innerText = xhr.responseText; 462 } 463} 464xhr.send(); 465</pre> 466<p> 467Additionally, be especially careful of resource retrieved via HTTP. If your 468extension is used on a hostile network, an network attacker (aka a <a href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">"man-in-the-middle"</a>) 469could modify the response and, potentially, attack your extension. Instead, 470prefer HTTPS whenever possible. 471</p> 472 473<!-- END AUTHORED CONTENT --> 474</div> 475 476 <!-- API PAGE --> 477 <div class="apiPage" style="display: none; "> 478 <a name="apiReference"></a> 479 <h2>API reference: chrome.apiname </h2> 480 481 <!-- PROPERTIES --> 482 <div class="apiGroup"> 483 <a name="properties"></a> 484 <h3 id="properties">Properties</h3> 485 486 <div> 487 <a></a> 488 <h4>getLastError</h4> 489 <div class="summary"> 490 <!-- Note: intentionally longer 80 columns --> 491 <span>chrome.extension</span><span>lastError</span> 492 </div> 493 <div> 494 </div> 495 </div> 496 497 </div> <!-- /apiGroup --> 498 499 <!-- METHODS --> 500 <div id="methodsTemplate" class="apiGroup"> 501 <a></a> 502 <h3>Methods</h3> 503 504 <!-- iterates over all functions --> 505 <div class="apiItem"> 506 <a></a> <!-- method-anchor --> 507 <h4>method name</h4> 508 509 <div class="summary"><span>void</span> 510 <!-- Note: intentionally longer 80 columns --> 511 <span>chrome.module.methodName</span>(<span><span>, </span><span></span> 512 <var><span></span></var></span>)</div> 513 514 <div class="description"> 515 <p class="todo">Undocumented.</p> 516 <p> 517 A description from the json schema def of the function goes here. 518 </p> 519 520 <!-- PARAMETERS --> 521 <h4>Parameters</h4> 522 <dl> 523 <div> 524 <div> 525 </div> 526 </div> 527 </dl> 528 529 <!-- RETURNS --> 530 <h4>Returns</h4> 531 <dl> 532 <div> 533 <div> 534 </div> 535 </div> 536 </dl> 537 538 <!-- CALLBACK --> 539 <div> 540 <div> 541 <h4>Callback function</h4> 542 <p> 543 The callback <em>parameter</em> should specify a function 544 that looks like this: 545 </p> 546 <p> 547 If you specify the <em>callback</em> parameter, it should 548 specify a function that looks like this: 549 </p> 550 551 <!-- Note: intentionally longer 80 columns --> 552 <pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre> 553 <dl> 554 <div> 555 <div> 556 </div> 557 </div> 558 </dl> 559 </div> 560 </div> 561 562 <!-- MIN_VERSION --> 563 <p> 564 This function was added in version <b><span></span></b>. 565 If you require this function, the manifest key 566 <a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a> 567 can ensure that your extension won't be run in an earlier browser version. 568 </p> 569 </div> <!-- /description --> 570 571 </div> <!-- /apiItem --> 572 573 </div> <!-- /apiGroup --> 574 575 <!-- EVENTS --> 576 <div id="eventsTemplate" class="apiGroup"> 577 <a></a> 578 <h3>Events</h3> 579 <!-- iterates over all events --> 580 <div class="apiItem"> 581 <a></a> 582 <h4>event name</h4> 583 584 <div class="summary"> 585 <!-- Note: intentionally longer 80 columns --> 586 <span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>); 587 </div> 588 589 <div class="description"> 590 <p class="todo">Undocumented.</p> 591 <p> 592 A description from the json schema def of the event goes here. 593 </p> 594 595 <!-- PARAMETERS --> 596 <div> 597 <h4>Parameters</h4> 598 <dl> 599 <div> 600 <div> 601 </div> 602 </div> 603 </dl> 604 </div> 605 </div> <!-- /decription --> 606 607 </div> <!-- /apiItem --> 608 609 </div> <!-- /apiGroup --> 610 611 <!-- TYPES --> 612 <div class="apiGroup"> 613 <a name="types"></a> 614 <h3 id="types">Types</h3> 615 616 <!-- iterates over all types --> 617 <div class="apiItem"> 618 <a></a> 619 <h4>type name</h4> 620 621 <div> 622 </div> 623 624 </div> <!-- /apiItem --> 625 626 </div> <!-- /apiGroup --> 627 628 </div> <!-- /apiPage --> 629 </div> <!-- /gc-pagecontent --> 630 </div> <!-- /g-section --> 631 </div> <!-- /codesiteContent --> 632 <div id="gc-footer" --=""> 633 <div class="text"> 634 <p> 635 Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>, 636 the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons 637 Attribution 3.0 License</a>, and code samples are licensed under the 638 <a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>. 639 </p> 640 <p> 641 ©2011 Google 642 </p> 643 644<!-- begin analytics --> 645<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script> 646<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script> 647 648<script type="text/javascript"> 649 // chrome doc tracking 650 try { 651 var engdocs = _gat._getTracker("YT-10763712-2"); 652 engdocs._trackPageview(); 653 } catch(err) {} 654 655 // code.google.com site-wide tracking 656 try { 657 _uacct="UA-18071-1"; 658 _uanchor=1; 659 _uff=0; 660 urchinTracker(); 661 } 662 catch(e) {/* urchinTracker not available. */} 663</script> 664<!-- end analytics --> 665 </div> 666 </div> <!-- /gc-footer --> 667 </div> <!-- /gc-container --> 668</body></html> 669
