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