diff options
Diffstat (limited to 'files/zh-cn/mozilla/tech/xpcom/reference')
25 files changed, 5875 insertions, 0 deletions
diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/index.html new file mode 100644 index 0000000000..92f0a47369 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/index.html @@ -0,0 +1,16 @@ +--- +title: XPCOM glue classes +slug: Mozilla/Tech/XPCOM/Reference/Glue_classes +tags: + - Classes + - Landing + - NeedsTranslation + - TopicStub + - XPCOM +translation_of: Mozilla/Tech/XPCOM/Reference/Glue_classes +--- +<p><span class="seoSummary">These "glue" classes are provided to make it easier to use XPCOM from C++ code.</span> When these classes are used by a component, you may need to link the component against the XPCOM glue library.</p> +<p></p><div class="row topicpage-table"> + <div class="section"><dl><dl><dt></dt></dl></dl></div> + <div class="section"><dl><dt class="landingPageList"><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Glue_classes/nsCOMPtr">使用nsCOMPtr</a></dt><dd class="landingPageList">这篇文档是对nsCOMPtr的一个总述。如果您所遇到的问题，无法在该文档中找到答案，可能就没有其他文档可以回答它了。您需要求助于XPCOM新闻组或者有nsCOMPtr使用经验的人来求解，或者根据自己的试验获取答案。</dd></dl></div> + </div><p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/nscomptr/getting_started_guide/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/nscomptr/getting_started_guide/index.html new file mode 100644 index 0000000000..32dedcf102 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/nscomptr/getting_started_guide/index.html @@ -0,0 +1,478 @@ +--- +title: 入门指南 +slug: Mozilla/Tech/XPCOM/Reference/Glue_classes/nsCOMPtr/Getting_Started_Guide +translation_of: Mozilla/Tech/XPCOM/Using_nsCOMPtr/Getting_Started_Guide +--- +<p>下面开始探讨智能指针问题。</p> +<h3 id="Introduction" name="Introduction">介绍</h3> +<h4 id="What_is_nsCOMPtr.3F" name="What_is_nsCOMPtr.3F">什么是 <code>nsCOMPtr</code>?</h4> +<p><code>nsCOMPtr</code> 是防止内存泄漏的一种工具。</p> +<p><code>nsCOMPtr</code> 是一种智能指针。 它是一个模板类，在使用上类似C/C++中的普通指针。如：可使用*或者->得到其所指定的内容。<code>nsCOMPtr</code>之所以智能，是因为它不像一般指向XPCOM对象的指针<code>，nsCOMPtr还管理</code><code>AddRef</code>, <code>Release</code>, 和<code>QueryInterface</code>方法。 <code>nsCOMPtr</code>是在以下源文件中定义的：</p> +<ul> + <li>{{ Source("xpcom/glue/nsCOMPtr.h", "xpcom/glue/nsCOMPtr.h") }}</li> + <li>{{ Source("xpcom/glue/nsCOMPtr.cpp", "xpcom/glue/nsCOMPtr.cpp") }}</li> +</ul> +<p>...though you probably don't want to look in there, just yet.</p> +<p><code>利用nsCOMPtr</code>，比使用原始的XPCOM接口指针，能够把代码写的更简短，更清晰，更明白，更安全。</p> +<h4 id=".5BXP.5DCOM_Basics:_Ownership_and_Reference_Counting" name=".5BXP.5DCOM_Basics:_Ownership_and_Reference_Counting">[XP]COM Basics: Ownership and Reference Counting</h4> +<p>这段是对XPCOM的一些基本问题的一个复习。对<code>nsCOMPtr</code>s的理解，需要对XPCOM有一个基本的认识。您可通过以下方式对XPCOM进行学习。<a class="external" href="http://www.develop.com/dbox/">Don Box</a>的<a class="external" href="http://www.amazon.com/exec/obidos/ASIN/0201634465">Essential COM</a> 介绍了COM的基本规则和使用。 Don Box 在 <a class="external" href="http://www.amazon.com/exec/obidos/ASIN/0201379686">Effective COM</a>.一书中更详尽的说明了COM的细节，缺陷和易犯的错误。您还需要对C++有基本的了解。这里列举三本比较有用的书：Bjarne Stroustrup 的 <a class="external" href="http://www.amazon.com/exec/obidos/ASIN/0201889544">The C++ Programming Language</a>，Scott Meyers 的 <a class="external" href="http://www.amazon.com/exec/obidos/ASIN/0201924889">Effective C++</a> 和 <a class="external" href="http://www.amazon.com/exec/obidos/ASIN/020163371X">More Effective C++</a>。</p> +<p>All XPCOM objects are allocated on the heap. Clients don't get to know much about the implementation of any such object. They reference it only through a pointer to an `interface', i.e., the static type of the pointer is a pointer to an abstract base class, the actual object pointed to is a class derived from that abstract base class. The XPCOM object is said to `implement that interface'. The client's reference to the object is typically called `an interface pointer'.</p> +<p>An object may implement many interfaces. Each interface is (at least conceptually) separately `reference counted'. That is, the interface keeps a count of the number of clients holding references to it. When that count goes to zero, the interface may <code>delete</code> itself. Clients are expected to keep this reference count accurate by incrementing it when they acquire a reference to the interface, and decrementing it before they let go. To facilitate this, all interfaces inherit from an abstract base class that provides the member functions <code>AddRef</code>, and <code>Release</code>.</p> +<p>A rule of XPCOM is that any function that creates or returns an interface pointer will have already <code>AddRef</code>ed it. The caller can then hold onto the reference indefinitely, calling <code>Release</code> when it no longer needs it. When the last pointer to an interface is <code>Release</code>d, the interface (and consequently, typically the underlying object) will <code>delete</code> itself. As long as there is an outstanding <code>AddRef</code> against the interface, it continues to exist. If you forget to call <code>Release</code>, the object will leak, i.e., the storage for that object will never be reclaimed. Leaks are bad <code><span class="nowiki">:-)</span></code>.</p> +<p>A reference through which you will call <code>AddRef</code> and <code>Release</code> is called an <strong>owning reference</strong>. It holds a stake in the underlying object. That object cannot go away until the owning reference has relinquished its claim. Not all references need to be owning references. In fact, if two objects somehow end up owning each other (even transitively) it becomes difficult for either of those object to be reclaimed without adding some `out-of-band' mechanism for breaking the ownership cycle. The document <a href="/en/XPCOM_ownership_guidelines" title="en/XPCOM_ownership_guidelines">Some COM Ownership Guidelines</a> provides some hints on when ownership is needed. The following lists are good starting point, but by no means complete.</p> +<p>You use an owning reference when</p> +<ul> + <li>you created the object;</li> + <li>you got the object from a function that <em>might</em> have created it, e.g., any `getter' function, such as <code>QueryInterface</code>, or <code>CreateInstance</code>. All good getters <code>AddRef</code> the interface pointers they produce, thus providing you with an owning reference;</li> + <li>you will hold onto the reference longer than the scope of the function in which you acquired it, e.g., you got it as a parameter, but you're hanging onto it in a member variable (see, for example, {{ web.link("#Comparison_1", "Comparison 1") }}, below).</li> +</ul> +<p>You don't need an owning reference when</p> +<ul> + <li>the object is passed in as a parameter, and you <em>don't</em> need to keep it any longer than the scope of this function;</li> + <li>the object's lifetime is known to contain yours in some well defined way, e.g., in the nodes of a tree, parent nodes keep owning references to their children, children need not keep owning references to their parents.</li> +</ul> +<p>It turns out that reference counting by hand is hard for programmers to get right. It may sound simple, but in practice it's very easy to forget to <code>Release</code> at the appropriate moment. Or to <code>AddRef</code> too many or too few times.</p> +<h4 id="How_does_nsCOMPtr_help.3F" name="How_does_nsCOMPtr_help.3F">How does <code>nsCOMPtr</code> help?</h4> +<p><code>nsCOMPtr</code> manages <code>AddRef</code>, <code>Release</code>, and other red-tape for you. An <code>nsCOMPtr</code> looks and acts as much like a raw XPCOM interface pointer as C allows, but it knows it owns the object it points to. This takes a little getting used to on your part, but ends up with less typing, clearer, safer code, and less leaks.</p> +<p>For instance, here is a typical snippet of code (at its most compact) where you assign a XPCOM interface pointer into a member variable, i.e., the body of a `setter' function, side-by-side using raw XPCOM interface pointers and <code>nsCOMPtr</code>s. </p> +<p>对照1.设置成员变量。</p> +<p> </p> +<table> + <caption> + </caption> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// raw [XP]COM interface pointers...</span> +<span class="comment">// given: |nsIFoo* mFooPtr;|</span> + +<span class="comment"><span class="nowiki">/* + |AddRef| the new value if it's not + |NULL|; assign it in; and |Release| + the old value, if any (so we don't + leak it). + + This order of assignment is special + and must be used to avoid particular + ownership bugs. + */</span></span> + +<strong>NS_IF_ADDREF(aFooPtr); +nsIFoo* temp = mFooPtr;</strong> +mFooPtr = aFooPtr; +<strong>NS_IF_RELEASE(temp);</strong> +</pre> + </td> + <td> + <pre class="eval"> +<span class="comment">// |nsCOMPtr|...</span> +<span class="comment">// given: |nsCOMPtr<nsIFoo> mFooPtr;|</span> + +<span class="comment"><span class="nowiki">/* + This assignment automatically + |Release|s the old value in + |mFooPtr|, if any, and |AddRef|s the + new one, in the appropriate sequence + to avoid the ownership bug mentioned + earlier. + */</span></span> + + + + + +mFooPtr = aFooPtr; + +</pre> + </td> + </tr> + </tbody> +</table> +<p>Additionally, the class using raw XPCOM interface pointers will need a destructor to <code>Release</code> <code>mFooPtr</code><span class="nowiki">; and a constructor to ensure that </span><code>mFooPtr</code> is initially set to <code>NULL</code> (or some other reasonable value).</p> +<p><code>nsCOMPtr</code> helps you write code that is leak-proof, exception safe, and significantly less verbose than you would with raw XPCOM interface pointers. With <code>nsCOMPtr</code>, you may never have to call <code>AddRef</code>, <code>Release</code>, or <code>QueryInterface</code> by hand.</p> +<p>You still have to understand XPCOM. You still have to know which functions return interface pointers that have already been <code>AddRef</code>ed and which don't. You still have to ensure your program logic doesn't produce circularly referencing garbage. <code>nsCOMPtr</code> is not a panacea. It is, however, helpful, easy to use, well-tested, and polite. It doesn't require that a function author cooperate with you, nor does your use force others to use it.</p> +<h3 id="Using_nsCOMPtr" name="Using_nsCOMPtr"><span style="font-family: monospace;">使用</span><code>nsCOMPtr</code></h3> +<h4 id="The_Basics" name="The_Basics">The Basics</h4> +<p>多数情况下，使用nsCOMPtr和一个一般的XPCOM接口指针是类似的。注意在声明中的细微区别。</p> +<table> + <caption> + 对照 2. 相似点: <code>nsCOMPtr</code>类似于 XPCOM接口指针</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// raw [XP]COM interface pointers...</span> + +nsIFoo<strong><span class="nowiki">*</span></strong> fooPtr <strong><span class="nowiki">= 0</span></strong><span class="nowiki">; + </span><span class="comment">// ...</span> +fooPtr->SomeFunction(x, y, z); +AnotherFunction(fooPtr); + +if ( fooPtr ) + <span class="comment">// ...</span> + +if ( fooPtr == foo2Ptr ) + <span class="comment">// ...</span> +</pre> + </td> + <td> + <pre class="eval"> +<span class="comment">// |nsCOMPtr|...</span> + +<strong>nsCOMPtr<</strong>nsIFoo<strong>></strong> fooPtr; +<span class="comment">// ...</span> +fooPtr->SomeFunction(x, y, z); +AnotherFunction(fooPtr); + +if ( fooPtr ) + <span class="comment">// ...</span> + +if ( fooPtr == foo2Ptr ) + <span class="comment">// ...</span> +</pre> + </td> + </tr> + </tbody> +</table> +<p> </p> +<p>有两点主要区别。第一：不需要也不再允许调用<code>AddRef</code> 和 <code>Release</code>方法。 </p> +<table> + <caption> + 对照 3. 不同点: <code>AddRef</code> <span style="font-family: monospace;">和 </span><code>Release</code> 对于 <code>nsCOMPtr</code>s 来说是非法的。</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// raw [XP]COM interface pointers...</span> +<span class="comment">// given: |nsIFoo* mFooPtr;|</span> + + <span class="comment">/* + Note: this sequence is not the + correct order to do assign + raw pointers anyway (see + {{ Anch("Comparison 1") }}) but I need it + for this comparison. + */</span> + +NS_IF_RELEASE(mFooPtr); + +mFooPtr = aFooPtr; +NS_IF_ADDREF(mFooPtr); + +</pre> + </td> + <td> + <pre class="eval"> +<span class="comment">// |nsCOMPtr|...</span> +<span class="comment">// given: |nsCOMPtr<nsIFoo> mFooPtr;|</span> + + <span class="comment">/* + You no longer need, nor will the + compiler let you, call |AddRef|, + or |Release|. + */</span> + + + +<span class="warning">NS_IF_RELEASE(mFooPtr);</span> + <span class="comment">// Error: |Release| is private</span> +mFooPtr = aFooPtr; +<span class="warning">NS_IF_ADDREF(mFooPtr);</span> + <span class="comment">// Error: |AddRef| is private</span> +</pre> + </td> + </tr> + </tbody> +</table> +<p> </p> +<p>第二：使用 <a href="/en/Using_nsCOMPtr/Reference_Manual#.60Out.27_Parameters:_getter_AddRefs" title="en/Using_nsCOMPtr/Reference_Manual#.60Out.27_Parameters:_getter_AddRefs"><code>getter_AddRefs</code></a> 标识nsCOMPtr，作为获取指针返回值的函数的参数，而不能只使用<code>nsCOMPtr</code>的地址作为参数。</p> +<table> + <caption> + 对照 4. 不同点: <span style="font-family: monospace;">当 </span><code>nsCOMPtr</code> 作为输出参数时，使用 getter_AddRefs。</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// raw [XP]COM interface pointers...</span> + +nsIFoo* foo; + +GetFoo(<strong>&</strong>foo); +</pre> + </td> + <td> + <pre class="eval"> +<span class="comment">// |nsCOMPtr|s...</span> + +nsCOMPtr<nsIFoo> foo; + +GetFoo(<strong>getter_AddRefs(</strong>foo<strong>)</strong>); +</pre> + </td> + </tr> + </tbody> +</table> +<p> </p> +<p>以上是对nsCOMPtrS的一些说明，基本涵盖了平日使用的90%。以下是在一些复杂情况下，对其的细节说明。</p> +<p> </p> +<h4 id="A_Few_Details" name="A_Few_Details">一些细节</h4> +<p> </p> +<p>以下是更多细节让您更了解 <code>nsCOMPtr</code>。</p> +<p>通常，通过调用 <code>QueryInterface 获取接口指针</code><span style="font-family: monospace;">。</span> <code>QueryInterface</code> 是一个 getter 函数，由以上方法，可通过 <code>getter_AddRefs</code> 方法来获取。</p> +<table> + <caption> + The hard way to <code>QueryInterface</code> into an <code>nsCOMPtr</code>.</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// A way (though not the best way) to |QueryInterface| into an |nsCOMPtr|...</span> + +nsCOMPtr<nsIFoo> foo; + +nsresult rv = bar->QueryInterface(NS_GET_IID(nsIFoo), getter_AddRefs(foo)); + + <span class="comment">// Or, if you're a savvy [XP]COM programmer,</span> + <span class="comment">// you use the type-safe version...</span> +nsresult rv = CallQueryInterface(bar, getter_AddRefs(foo)); +</pre> + </td> + </tr> + </tbody> +</table> +<p><code>因为 QueryInterface</code> 使用频繁，<code>nsCOMPtr</code> 提供了一种特殊方式对其调用。这种方式是类型安全的，<code>QueryInterface的返回值能</code>直接构造nsCOMPtr。这种构造方式比通过赋值进行构造效率更高。这种方式是 <a href="/en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A.2C_nsresult.2A_.29" title="en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A.2C_nsresult.2A_.29"><code>do_QueryInterface</code></a> 。通过使用这种方式，以上例子可写为：</p> +<table> + <caption> + How to <code>QueryInterface</code> into an <code>nsCOMPtr</code>.</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// The best way to |QueryInterface| into an |nsCOMPtr|...</span> + +nsresult rv; +nsCOMPtr<nsIFoo> foo( <strong>do_QueryInterface(</strong>bar, &rv<strong>)</strong> ); + + <span class="comment">// Or, if you don't care about the |nsresult|</span> +nsCOMPtr<nsIFoo> foo( <strong>do_QueryInterface(</strong>bar<strong>)</strong> ); +</pre> + </td> + </tr> + </tbody> +</table> +<p><code>nsCOMPtr</code> happily calls <code>AddRef</code> and <code>Release</code> implicitly. This same favor is <em>not</em> extended to <code>QueryInterface</code>. <code>nsCOMPtr</code> does not <code>QueryInterface</code> on assignment without your explicit permission in the form of the <code>do_QueryInterface</code> directive. You need never worry about hidden queries. However, be aware that if you <em>should</em> have queried but didn't, e.g., when assigning in a raw pointer where C allows the assignment, but XPCOM wouldn't, <code>nsCOMPtr</code> will <a href="/en/Using_nsCOMPtr/Reference_Manual#Type_Safeguards" title="en/Using_nsCOMPtr/Reference_Manual#Type_Safeguards">assert at runtime</a>. Use <code>do_QueryInterface</code> whenever you assign in a pointer to a XPCOM interface of a different type, even if that type happens to derive from the base type of the <code>nsCOMPtr</code></p> +<p> </p> +<table> + <caption> + 对照6. <code>do_QueryInterface</code> 避免了XPCOM 中的类型错误。</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +class nsIBar + : public nsIFoo ... { ... }; + +nsIBar* p = ...; + + <span class="comment">// C thinks every |nsIBar*| is an</span> + <span class="comment">// |nsIFoo*|, therefore, C allows</span> + <span class="comment">// this...</span> +nsCOMPtr<nsIFoo> <span class="warning">foo = p;</span> + <span class="comment">// ...even though it is an [XP]COM</span> + <span class="comment">// type error</span> +</pre> + </td> + <td> + <pre class="eval"> +class nsIBar + : public nsIFoo ... { ... }; + +nsIBar* p = ...; + + + + <span class="comment">// No type error here...</span> +nsCOMPtr<nsIFoo> foo( <strong>do_QueryInterface(</strong>p<strong>)</strong> ); + + +</pre> + </td> + </tr> + </tbody> +</table> +<p>Remember, the C type system and the XPCOM type system are really two independent things. Because XPCOM interfaces are expressed as abstract C base classes, you may be tempted to let C handle the differences, or to use C casts to navigate between interface types. This is wrong. The only sanctioned way to get between XPCOM types is with <code>QueryInterface</code>. In the example above, there is no reason to assume that the <code>nsIFoo*</code> C pulls out of <code>p</code> would be the same one that <code>p->QueryInterface()</code> would return.</p> +<p><a href="/en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_getter_AddRefs.28_T.2A_.29" title="en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_getter_AddRefs.28_T.2A_.29"><code>dont_AddRef</code></a> is a similar directive that helps you when you assign in a pointer that has already been <code>AddRef</code>ed, e.g., because you called a getter that returned the pointer as its function result.</p> +<table> + <caption> + Using <code>dont_AddRef</code>.</caption> + <tbody> + <tr> + <td> + <pre class="eval"> +nsCOMPtr<nsIFoo> foo( <strong>dont_AddRef(</strong>CreateFoo()<strong>)</strong> ); + <span class="comment">// |CreateFoo| |AddRef|s its result, as all good getters do</span> +</pre> + </td> + </tr> + </tbody> +</table> +<h4 id="Something_nsCOMPtr_Doesn.27t_Do" name="Something_nsCOMPtr_Doesn.27t_Do">Something <code>nsCOMPtr</code> <em>Doesn't</em> Do</h4> +<p>An <code>nsCOMPtr</code> does all that is necessary to behave as an owning reference. A given <code>nsCOMPtr</code> does not, however, cooperate in making <em>other</em> owning pointers. After learning how <code>nsCOMPtr</code> automatically <code>AddRef</code>s a pointer as it is being assigned <em>in</em>, the natural assumption is that it does the same thing when assigning <em>out</em>. Here is a snippet of code that demonstrates this misconception.</p> +<table> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// Incorrect assumptions about |nsCOMPtr|...</span> + +nsresult +nsCacheRecord::GetFileSpec( nsIFileSpec** aFileSpecResult ) + <span class="comment">/* + ...fills in the callers |nsFileSpec*| (which the caller supplied + the address of) with a copy of my member variable |mFileSpec|, + an |nsCOMPtr|. I.e., this function is a `getter'. + + Remember: good [XP]COM getters always |AddRef| their result. + */</span> + { + <span class="comment">// ...</span> + *aFileSpec = mFileSpec; + <span class="warning"><span class="comment">// the |nsCOMPtr| should take care of the refcount here, right?</span></span> + return NS_OK; + } +</pre> + </td> + </tr> + </tbody> +</table> +<p>Plainly, the author believed (though perhaps with some question) that the <code>nsCOMPtr</code>, <code>mFileSpec</code>, would <code>AddRef</code> automatically as it was assigned into <code><span class="nowiki">*aFileSpec</span></code>. This is <em>not</em> the case. An <code>nsCOMPtr</code> automatically calls <code>AddRef</code> and <code>Release</code> (only) on its <em>own</em> behalf. In all other situations, it is designed to be a drop in replacement for a raw XPCOM pointer. Where ever an <code>nsCOMPtr</code> is used in a situation where a raw pointer is needed, the <code>nsCOMPtr</code> automatically provides one.</p> +<table> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// |nsCOMPtr| produces a raw pointer when needed...</span> + +nsCOMPtr<nsIFoo> foo = ...; + + <span class="comment">// 1. Assigning into a raw pointer</span> +nsIFoo* raw_foo = foo; + + <span class="comment">// 2. Assigning into another |nsCOMPtr|</span> +nsCOMPtr<nsIFoo> foo2 = foo; + + <span class="comment">// 3. As a parameter</span> +SetFoo(foo); + + <span class="comment">// 4. Testing the value in an |if| expression</span> + <span class="comment">// 5. Calling a member function</span> +if ( foo ) + foo->DoSomething(); +</pre> + </td> + </tr> + </tbody> +</table> +<p>In all of these cases, pretty much the exact same code is executed (case 2 is slightly different, but the intent is the same). In each case, you are essentially extracting the raw pointer value for your own purpose. If the <code>nsCOMPtr</code> <code>AddRef</code>ed the value each time you did that, cases 4 and 5 would obviously always generate leaks. <code>SetFoo</code>, from case 3, would have to be written two different ways when given an <code>nsCOMPtr</code>, it would know the value was already <code>AddRef</code>ed, and when given a raw pointer it would assume the value was not <code>AddRef</code>ed. Actually the contradictions run deeper than that. All these cases show that automatically <code>AddRef</code>ing on `output' makes <code>nsCOMPtr</code>s and raw-pointers act differently from the point of view of the clients. The goal is to make them act the same so that <code>nsCOMPtr</code>s can be a drop in replacement (modulo managing its own `ownership').</p> +<p>Given what you now know, the rule is predictable. As described above, and unless you tell it otherwise, an <code>nsCOMPtr</code> <code>AddRef</code>s when you assign <em>in</em> to it. It does nothing when you assign <em>out</em> of it.</p> +<h4 id="Where_should_I_use_nsCOMPtrs.3F" name="Where_should_I_use_nsCOMPtrs.3F">Where should I use <code>nsCOMPtr</code>s?</h4> +<p>You should use an <code>nsCOMPtr</code> any place you use an interface pointer as an owning reference, i.e., where you call <code>AddRef</code> and <code>Release</code> on it. You should use <code>nsCOMPtr</code> as a member variable, where it will simplify setters, and eliminate constructors, destructors, and assignment operators. You should use <code>nsCOMPtr</code> on the stack, where it makes calling <code>QueryInterface</code> almost pleasant, and eliminates the complex logic that falls out of error handling.</p> +<h4 id="Where_shouldn.27t_I_use_nsCOMPtrs.3F" name="Where_shouldn.27t_I_use_nsCOMPtrs.3F">Where shouldn't I use <code>nsCOMPtr</code>s?</h4> +<p>Don't use <code>nsCOMPtr</code>s where you don't need an owning reference. See <a href="/en/XPCOM_ownership_guidelines" title="en/XPCOM_ownership_guidelines">Some COM Ownership Guidelines</a>. <code>nsCOMPtr</code> is designed to be used with XPCOM interfaces, so don't use it with non-interfaces with specific exceptions described <a href="/en/Using_nsCOMPtr/Getting_Started_Guide#nsCOMPtrs_for_non-interface_classes" title="en/Using_nsCOMPtr/Getting_Started_Guide#nsCOMPtrs_for_non-interface_classes">below</a>. Don't use <code>nsCOMPtr</code>s in XPCOM interfaces. Don't use them in plain old C code; <code>nsCOMPtr</code>s are, of course, a C only construct. <a href="/en/Using_nsCOMPtr/Reference_Manual#Casting" title="en/Using_nsCOMPtr/Reference_Manual#Casting">Never cast</a> an <code>nsCOMPtr</code>, it's almost guaranteed to leak.</p> +<h4 id="nsCOMPtrs_for_non-interface_classes" name="nsCOMPtrs_for_non-interface_classes"><code>nsCOMPtr</code>s for non-interface classes</h4> +<p>Appropriately formatted answer to come, in the meanwhile, the full details are available in <a class="link-news" href="news://news.mozilla.org/scc-3E1526.12182423042001@h-204-29-187-152.netscape.com">this news posting</a> (<a class="external" href="http://groups.google.com/group/netscape.public.mozilla.xpcom/browse_frm/thread/77258f1cd7d99773/268b949066f2ba4a?hl=de&q=#268b949066f2ba4a" title="http://groups.google.com/group/netscape.public.mozilla.xpcom/browse_frm/thread/77258f1cd7d99773/268b949066f2ba4a?hl=de&q=#268b949066f2ba4a">via Google Groups</a>).</p> +<h4 id="nsCOMPtrs_in_function_signatures" name="nsCOMPtrs_in_function_signatures"><code>nsCOMPtr</code>s in function signatures</h4> +<p>In general, you won't want to use <code>nsCOMPtr</code> in the signature of XPCOM (i.e., `scriptable') functions. <code>nsCOMPtr</code> is not currently directly supported by IDL. However, you may sometime be tempted to use an <code>nsCOMPtr</code> in a non-scriptable function.</p> +<h5 id="nsCOMPtr.3CT.3E_f.28.29_don.27t_return_an_nsCOMPtr" name="nsCOMPtr.3CT.3E_f.28.29_don.27t_return_an_nsCOMPtr"><span class="warning"><code>nsCOMPtr<T> f()</code></span> 不返回 <code>nsCOMPtr</code></h5> +<p>This practice is dangerous. Returning an <code>AddRef</code>ed pointer in almost any form as a function result leads to several potential errors, some of which are leaks, some of which are dangling pointers. Returning an <code>nsCOMPtr</code> may seem like a good idea (since it tells clients you are giving them ownership), however it can be the cause of an dangling pointer. Consider:</p> +<table> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// Don't return |nsCOMPtr|s...</span> +nsCOMPtr<nsIFoo> CreateFoo(); +<span class="comment">// ...</span> + +<span class="warning">nsIFoo* myFoo = CreateFoo();</span> <span class="comment">// Oops: |myFoo| now dangles!</span> + <span class="comment">// |CreateFoo| returns an |nsCOMPtr|, which</span> + <span class="comment">// automatically |Release|s right after this</span> + <span class="comment">// assignment. Now |myFoo| refers to a</span> + <span class="comment">// deleted object.</span> +</pre> + </td> + </tr> + </tbody> +</table> +<p>You can tell callers you are giving them ownership in a way that doesn't pose this hazard by returning a <code>already_AddRefed<T></code> (see bug <a class="external" href="http://bugzilla.mozilla.org/show_bug.cgi?id=59212"><span class="nowiki">#59212</span></a>). An <code>nsCOMPtr</code> knows not to <code>AddRef</code> a value that is <code>already_AddRefed</code>.</p> +<table> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// Preferred form: if you must return a pointer, use |already_AddRefed|...</span> +already_AddRefed<nsIFoo> CreateFoo(); +<span class="comment">// ...</span> + +nsIFoo* myFoo1 = CreateFoo(); <span class="comment">// doesn't dangle</span> +nsCOMPtr<nsIFoo> myFoo2( CreateFoo() ); <span class="comment">// doesn't leak</span> +nsCOMPtr<nsIFoo> myFoo3( dont_AddRef(CreateFoo()) ); <span class="comment">// redundant, but legal and correct</span> +</pre> + </td> + </tr> + </tbody> +</table> +<p>Compare this to the most frequent leaks caused by returning a raw pointer you have already <code>AddRef</code>ed:</p> +<table> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// Don't return raw pointers; that incites leaks...</span> +nsIFoo* CreateFoo(); <span class="comment">// returns an |AddRef|ed pointer</span> +<span class="comment">// ...</span> + +<span class="warning">nsCOMPtr<nsIFoo> myFoo = CreateFoo();</span> <span class="comment">// Oops: leak;</span> +nsCOMPtr<nsIFoo> myFoo( <span class="notice">dont_AddRef(</span>CreateFoo()<span class="notice">)</span> ); + <span class="comment">// Since |CreateFoo| already |AddRef|s its result, we must remind</span> + <span class="comment">// our |nsCOMPtr| not to. It's easy to forget. Prevent it in advance</span> + <span class="comment">// by not returning pointers as function results, or else by returning</span> + <span class="comment">// an |already_AddRefed<T>| as above.</span> +</pre> + </td> + </tr> + </tbody> +</table> +<h5 id="void_f.28_nsCOMPtr.3CT.3E_.29_don.27t_pass_an_nsCOMPtr_by_value" name="void_f.28_nsCOMPtr.3CT.3E_.29_don.27t_pass_an_nsCOMPtr_by_value"><span class="warning"><code>void f( nsCOMPtr<T> )</code></span> don't pass an <code>nsCOMPtr</code> by value</h5> +<p>This practice is wasteful, but not otherwise harmful. There is no need to <code>AddRef</code> parameters, as they are guaranteed to live as long as the function call. You only need to <code>AddRef</code> them as you store them in a structure that will live longer than the function call. Which means the appropriate member of that structure should be an <code>nsCOMPtr</code>, not the function parameter. Additionally, this signature may confuse callers into thinking they need an <code>nsCOMPtr</code> just to call the function.</p> +<h5 id="void_f.28_const_nsCOMPtr.3CT.3E&_.29_don.27t_pass_an_nsCOMPtr_by_const_reference" name="void_f.28_const_nsCOMPtr.3CT.3E&_.29_don.27t_pass_an_nsCOMPtr_by_const_reference"><span class="warning"><code>void f( const nsCOMPtr<T>& )</code></span> don't pass an <code>nsCOMPtr</code> by <code>const</code> reference</h5> +<p>Exactly as the signature above, this practice is wasteful, but not otherwise harmful, and has the same impact as passing an <code>nsCOMPtr</code> by value if the caller only supplied a raw pointer.</p> +<h5 id="void_f.28_nsCOMPtr.3CT.3E.2A_.29_avoid_passing_an_nsCOMPtr_by_address.2C_if_possible" name="void_f.28_nsCOMPtr.3CT.3E.2A_.29_avoid_passing_an_nsCOMPtr_by_address.2C_if_possible"><span class="warning"><code>void f( nsCOMPtr<T>* )</code></span> avoid passing an <code>nsCOMPtr</code> by address, if possible</h5> +<p>This practice requires callers to have an <code>nsCOMPtr</code>, and requires them to do a little extra work, as <code>operator&</code> for <code>nsCOMPtr</code>s is <code>private</code> (to help prevent <a href="/en/Using_nsCOMPtr/Reference_Manual#Casting" title="en/Using_nsCOMPtr/Reference_Manual#Casting">leaks caused by casting</a>; also see {{ Bug(59414) }}). This is an acceptable way to declare `in/out' parameters, but prefer passing <code>nsCOMPtr</code>s by reference, as below.</p> +<table> + <tbody> + <tr> + <td> + <pre class="eval"> +<span class="comment">// Passing an |nsCOMPtr| by pointer requires extra work...</span> +void f( nsCOMPtr<nsIFoo>* ); +<span class="comment">// ...</span> + +nsCOMPtr<nsIFoo> myFoo = ...; + +f( <span class="notice">address_of(</span>myFoo<span class="notice">)</span> ); +</pre> + </td> + </tr> + </tbody> +</table> +<h5 id="void_f.28_nsCOMPtr.3CT.3E&_.29_do_pass_an_nsCOMPtr_by_reference_for_.60in.2Fout.27_parameters" name="void_f.28_nsCOMPtr.3CT.3E&_.29_do_pass_an_nsCOMPtr_by_reference_for_.60in.2Fout.27_parameters"><code>void f( nsCOMPtr<T>& )</code> do pass an <code>nsCOMPtr</code> by reference for `in/out' parameters</h5> +<p>This is the prefered scheme for providing `in/out' parameters. If you were to use a raw pointer instead, your function couldn't know what ownership relationship the caller had to the input value, and hence, couldn't know whether to <code>Release</code> it or not before assigning in the new value. By declaring the parameter as an <code>nsCOMPtr&</code>, the relationship is explicit.</p> +<h3 id="Summary" name="Summary">Summary</h3> +<p>An <code>nsCOMPtr</code> is an owning reference. Whatever it points to has been <code>AddRef</code>ed, counting the <code>nsCOMPtr</code> as one of its `owners'. An <code>nsCOMPtr</code> always calls <code>Release</code> before letting go, whether the <code>nsCOMPtr</code> is letting go so that it can point to a different object, or because the <code>nsCOMPtr</code> is going out of scope. Any time a new value is assigned into an <code>nsCOMPtr</code>, the <code>nsCOMPtr</code> automatically always <code>Release</code>s its old referent, if any, and (unless you tell it you already have) <code>AddRef</code>s the new.</p> +<p>You use an <code>nsCOMPtr</code> exactly as you would a raw XPCOM interface pointer in almost all cases. You won't have to explictly call <code>AddRef</code> or <code>Release</code> through it, nor will the compiler allow it. The only place you can't use an <code>nsCOMPtr</code> without change is where a raw XPCOM interface pointer is an `out' parameter. In this case, you wrap the <code>nsCOMPtr</code> with <a href="/en/Using_nsCOMPtr/Reference_Manual#.60Out.27_Parameters:_getter_AddRefs" title="en/Using_nsCOMPtr/Reference_Manual#.60Out.27_Parameters:_getter_AddRefs"><code>getter_AddRefs</code></a> (see {{ web.link("#Comparison_4", "Comparison 4") }}).</p> +<p>When assigning into an <code>nsCOMPtr</code>, you will usually just supply another pointer (either a raw XPCOM interface pointer or an <code>nsCOMPtr</code>), with no additional directives { web.link("#Comparison_1", "Comparison 1") }}). As stated above, with no directives, the <code>nsCOMPtr</code> will <code>Release</code> its old referent, if any, and <code>AddRef</code> the new. This is appropriate when the thing you're assigning in hasn't yet been <code>AddRef</code>ed to account for the new reference. This is typically the case when you are assigning in a pointer that you <em>didn't</em> call a function to get, e.g., one that was passed in as a parameter, or that you pulled out of a structure.</p> +<p>You can tell <code>nsCOMPtr</code> it doesn't need to <code>AddRef</code> the new value on assignment by wrapping the new value in <a href="/en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_getter_AddRefs.28_T.2A_.29" title="en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_dont_AddRef.28_T.2A_.29.2CnsCOMPtr.3CT.3E_.3D_getter_AddRefs.28_T.2A_.29"><code>dont_AddRef</code></a>. Do this, for example, when you got the new value from a function which, like all good XPCOM getters, already called <code>AddRef</code> on your behalf.</p> +<p>You may not assign in a pointer to a different interface type; you must first query it to the right type (see, e.g., {{ web.link("#Comparison_6", "Comparison 6") }} and the surrounding discussion). <code>nsCOMPtr</code> <em>never</em> calls <code>QueryInterface</code> implicitly, i.e., you must call it yourself, or explictly ask <code>nsCOMPtr</code> to call it with <a href="/en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A.2C_nsresult.2A_.29" title="en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A_.29.2CnsCOMPtr.3CT.3E_.3D_do_QueryInterface.28_nsISupports.2A.2C_nsresult.2A_.29"><code>do_QueryInterface</code></a>. The <code>do_QueryInterface</code> directive allows you to do the query as part of the assignment. This better facilitates constructing an <code>nsCOMPtr</code> directly from the right value, rather than constructing it and assigning in the correct value later. Construction alone is more efficient than construction followed by assignment. Prefer construction over assignment whereever reasonable. Be careful not to apply <code>do_QueryInterface</code> to a function returning an <code>AddRef</code>ed pointer [see <a href="/en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_.2F.2A_call_QueryInterface_but_don.27t_AddRef_.2A.2F" title="en/Using_nsCOMPtr/Reference_Manual#nsCOMPtr.3CT.3E_.3D_.2F.2A_call_QueryInterface_but_don.27t_AddRef_.2A.2F">this short section</a> for an explanation]</p> +<p>For more details, continue on to the <a href="/en/Using_nsCOMPtr/Reference_Manual" title="en/Using_nsCOMPtr/Reference_Manual">Reference Manual</a>.</p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/nscomptr/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/nscomptr/index.html new file mode 100644 index 0000000000..d9c427784a --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/glue_classes/nscomptr/index.html @@ -0,0 +1,56 @@ +--- +title: 使用nsCOMPtr +slug: Mozilla/Tech/XPCOM/Reference/Glue_classes/nsCOMPtr +translation_of: Mozilla/Tech/XPCOM/Reference/Glue_classes/nsCOMPtr +--- +<p>这篇文档是对nsCOMPtr的一个总述。如果您所遇到的问题，无法在该文档中找到答案，可能就没有其他文档可以回答它了。您需要求助于XPCOM新闻组或者有nsCOMPtr使用经验的人来求解，或者根据自己的试验获取答案。</p> + +<p>如果您尚未使用过nsCOMPtr，您正好可从这里开始。当您使用了一段时间后，或者遇到了不熟悉的领域，或者出现编译错误，您可返回该文档，在参考手册或者FAQ中求助。</p> + +<h2 id="Contents" name="Contents">内容</h2> + +<ol> + <li><a href="/en/Using_nsCOMPtr/Status,_Recent_Changes,_and_Plans" title="en/Using_nsCOMPtr/Status,_Recent_Changes,_and_Plans">状态，最新修改和计划</a> + + <ol> + <li><a href="/en/Using_nsCOMPtr/Status,_Recent_Changes,_and_Plans#Recent_changes_to_nsCOMPtr" title="en/Using_nsCOMPtr/Status,_Recent_Changes,_and_Plans#Recent_changes_to_nsCOMPtr"><span style="font-family: monospace;">对</span><code>nsCOMPtr的最新修改</code></a></li> + </ol> + </li> + <li><a href="/en/Using_nsCOMPtr/Getting_Started_Guide" title="en/Using_nsCOMPtr/Getting_Started_Guide">入门指南</a> + <ol> + <li><a href="/en/Using_nsCOMPtr/Getting_Started_Guide#Introduction" title="en/Using_nsCOMPtr/Getting_Started_Guide#Introduction">介绍</a></li> + <li><a href="/en/Using_nsCOMPtr/Getting_Started_Guide#Using_nsCOMPtr" title="en/Using_nsCOMPtr/Getting_Started_Guide#Using_nsCOMPtr">使用 <code>nsCOMPtr</code></a></li> + <li><a href="/en/Using_nsCOMPtr/Getting_Started_Guide#Summary" title="en/Using_nsCOMPtr/Getting_Started_Guide#Summary">小结</a></li> + </ol> + </li> + <li><a href="/en/Using_nsCOMPtr/Reference_Manual" title="en/Using_nsCOMPtr/Reference_Manual">参考手册</a> + <ol> + <li><a href="/en/Using_nsCOMPtr/Reference_Manual#The_Basics" title="en/Using_nsCOMPtr/Reference_Manual#The_Basics">基本原理</a></li> + <li><a href="/en/Using_nsCOMPtr/Reference_Manual#Initialization_and_Assignment" title="en/Using_nsCOMPtr/Reference_Manual#Initialization_and_Assignment">初始化和赋值</a></li> + <li><a href="/en/Using_nsCOMPtr/Reference_Manual#Using_an_nsCOMPtr.3CT.3E_as_a_T.2A" title="en/Using_nsCOMPtr/Reference_Manual#Using_an_nsCOMPtr.3CT.3E_as_a_T.2A">Using an <code>nsCOMPtr<T></code> as a <code>T*</code></a></li> + <li><a href="/en/Using_nsCOMPtr/Reference_Manual#Efficiency_and_Correctness" title="en/Using_nsCOMPtr/Reference_Manual#Efficiency_and_Correctness">Efficiency and Correctness</a></li> + <li><a href="/en/Using_nsCOMPtr/Reference_Manual#Compiler_Annoyances" title="en/Using_nsCOMPtr/Reference_Manual#Compiler_Annoyances">Compiler Annoyances</a></li> + </ol> + </li> + <li><a href="/en/Using_nsCOMPtr/Frequently_Asked_Questions" title="en/Using_nsCOMPtr/Frequently_Asked_Questions">FAQ</a> + <ol> + <li><a href="/en/Using_nsCOMPtr/Frequently_Asked_Questions#Buildtime_Errors" title="en/Using_nsCOMPtr/Frequently_Asked_Questions#Buildtime_Errors">编译时错误</a></li> + <li><a href="/en/Using_nsCOMPtr/Frequently_Asked_Questions#Runtime_Errors" title="en/Using_nsCOMPtr/Frequently_Asked_Questions#Runtime_Errors">运行时错误</a></li> + <li><a href="/en/Using_nsCOMPtr/Frequently_Asked_Questions#How_do_I..." title="en/Using_nsCOMPtr/Frequently_Asked_Questions#How_do_I...">How do I...</a></li> + <li><a href="/en/Using_nsCOMPtr/Frequently_Asked_Questions#General" title="en/Using_nsCOMPtr/Frequently_Asked_Questions#General">General</a></li> + <li><a href="/en/Using_nsCOMPtr/Frequently_Asked_Questions#Bibliography" title="en/Using_nsCOMPtr/Frequently_Asked_Questions#Bibliography">Bibliography</a></li> + </ol> + </li> +</ol> + +<div class="originaldocinfo"> +<h2 id="Original_Document_Information" name="Original_Document_Information">Original Document Information</h2> + +<ul> + <li>Author(s): <a class="link-mailto" href="mailto:scc@mozilla.org">Scott Collins</a></li> + <li>Last Updated Date: December 11, 2001</li> + <li>Copyright Information: Copyright © 1999, 2000 by the Mozilla organization; use is subject to the <a class="external" href="http://www.mozilla.org/MPL/">MPL</a>. Portions of this content are © 1998–2007 by individual mozilla.org contributors; content available under a Creative Commons license | <a class="external" href="http://www.mozilla.org/foundation/licensing/website-content.html">Details</a>.</li> +</ul> +</div> + +<p> </p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/index.html new file mode 100644 index 0000000000..188a822ae6 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/index.html @@ -0,0 +1,14 @@ +--- +title: XPCOM reference +slug: Mozilla/Tech/XPCOM/Reference +translation_of: Mozilla/Tech/XPCOM/Reference +--- +<p>This reference describes the interfaces and functions provided by the <a href="/en-US/docs/Mozilla/Tech/XPCOM">XPCOM</a> library. In addition, it details the various helper classes and functions, as well as the components, provided by the <a href="/en-US/docs/Mozilla/Tech/XPCOM/Glue">XPCOM glue</a> library. The contents herein are oriented primarily toward extension developers and people embedding XPCOM in other projects.</p> +<div class="note"> + <p><strong>Note:</strong> If you're working on a module in the Mozilla codebase that's compiled with the <code>MOZILLA_INTERNAL_API</code> flag set, some of these APIs -- the string functions and classes in particular -- are not the ones you should be using. See the <a href="/en-US/docs/Mozilla/Tech/XPCOM/Guide/Internal_strings">XPCOM internal string guide</a> for documentation of the internal string API used within the Mozilla codebase.</p> +</div> +<p></p><div class="row topicpage-table"> + <div class="section"><dl><dl><dt class="landingPageList"><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Glue_classes">XPCOM glue classes</a></dt><dd class="landingPageList">These "glue" classes are provided to make it easier to use XPCOM from C++ code.</dd><dt class="landingPageList"><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface">XPCOM Interface Reference</a></dt><dd class="landingPageList"><span class="long_text short_text" id="result_box" lang="zh-CN"><span>这是一个</span><span>由</span><span>Mozilla平台</span><span>提供</span><span>的</span><span>XPCOM接口</span><span>的</span><span>参考</span></span>.</dd></dl></dl></div> + <div class="section"><dl><dt></dt></dl></div> + </div><p></p> +<p>Many XPCOM pages return an <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Core_functions/nsresult">nsresult</a></code>. Prior to Gecko 19 (Firefox 19 / Thunderbird 19 / SeaMonkey 2.16), this was an integer that simply returned an error code. It is now a strongly typed <code>enum</code> when XPCOM is built using a C++11 compiler. This causes compile-time errors to occur when improper values are returned as nsresult values, thereby making it easier to catch many bugs.</p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/index.html new file mode 100644 index 0000000000..da50238f6f --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/index.html @@ -0,0 +1,11 @@ +--- +title: XPCOM Interface Reference +slug: Mozilla/Tech/XPCOM/Reference/Interface +translation_of: Mozilla/Tech/XPCOM/Reference/Interface +--- +<p><span class="long_text short_text" id="result_box" lang="zh-CN"><span>这是一个</span><span>由</span><span>Mozilla平台</span><span>提供</span><span>的</span><span>XPCOM接口</span><span>的</span><span>参考</span></span>.</p> +<div style=""><ul><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIAccessibleProvider">nsIAccessibleProvider</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboard">nsIClipboard</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboardHelper">nsIClipboardHelper</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleService">nsIConsoleService</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMClientRect">nsIDOMClientRect</a></li><li><a href="/zh-CN/docs/nsIDOMParser">nsIDOMParser</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDirectoryServiceProvider">nsIDirectoryServiceProvider</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile">nsIFile</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker">nsIFilePicker</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIHttpChannel">nsIHttpChannel</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIIdleService">nsIIdleService</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile">nsILocalFile</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIProcess">nsIProcess</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPrompt">nsIPrompt</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService">nsIPromptService</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIScriptableUnicodeConverter">nsIScriptableUnicodeConverter</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISyncMessageSender">nsISyncMessageSender</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsITimer">nsITimer</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/NsITraceableChannel">nsITraceableChannel</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIURI">nsIURI</a></li><li><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest">nsIXMLHttpRequest</a></li></ul></div> +<h2 id="See_also" name="See_also">相关链接</h2> +<ul> <li><a href="/zh-cn/XPCOM_Interface_Reference_group" title="https://developer.mozilla.org/zh-cn/XPCOM_Interface_Reference_group">Interfaces grouped by function</a></li> +</ul> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiaccessibleprovider/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiaccessibleprovider/index.html new file mode 100644 index 0000000000..488e504556 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiaccessibleprovider/index.html @@ -0,0 +1,45 @@ +--- +title: nsIAccessibleProvider +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIAccessibleProvider +tags: + - Accessibility + - Interfaces +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIAccessibleProvider +--- +<p> </p> +<p><br> + </p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/accessible/public/nsIAccessibleProvider.idl" rel="custom">accessible/public/nsIAccessibleProvider.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +<i>Please add a summary to this article.</i> +</span> + +<div style="background: #eee; padding: 2px;"> +<span> </span> +<span style="text-align: right; float: right;">最后修改于Gecko 1.9 (Firefox 3)</span></div> +</div><p></p> +<p>Inherits from: <a href="cn/NsISupports">nsISupports</a></p> +<h2 id="Attributes" name="Attributes">Attributes</h2> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Attribute</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>accessible</code></td> + <td><code><a href="cn/NsIAccessible">nsIAccessible</a></code></td> + <td>Returns an accessible. + <i> + Read only</i> + </td> + </tr> + </tbody> +</table> +<h3 id="See_also" name="See_also">See also</h3> +<ul> + <li><a href="cn/Accessibility">Accessibility</a></li> + <li><a href="cn/NsIAccessible">nsIAccessible</a></li> +</ul> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiclipboard/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiclipboard/index.html new file mode 100644 index 0000000000..a1778f2cbb --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiclipboard/index.html @@ -0,0 +1,91 @@ +--- +title: nsIClipboard +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboard +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboard +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/widget/public/nsIClipboard.idl" rel="custom">widget/public/nsIClipboard.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +This interface supports basic clipboard operations such as: setting, retrieving, emptying, matching and supporting clipboard data. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)</span></div> +</div><p></p> +<h2 id="Method_overview" name="Method_overview"><span class="long_text short_text" id="result_box" lang="zh-CN"><span>方法</span><span>概述</span></span></h2> +<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#emptyClipboard()">emptyClipboard</a>(in long aWhichClipboard);</code></td> </tr> <tr> <td><code>void <a href="#forceDataToClipboard()">forceDataToClipboard</a>(in long aWhichClipboard);</code> <span class="inlineIndicator obsolete obsoleteInline" title="(Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)">已废弃 Gecko 1.8</span></td> </tr> <tr> <td><code>void <a href="#getData()">getData</a>(in nsITransferable aTransferable, in long aWhichClipboard);</code></td> </tr> <tr> <td><code>boolean <a href="#hasDataMatchingFlavors()">hasDataMatchingFlavors</a>([array, size_is(aLength)] in string aFlavorList, in unsigned long aLength, in long aWhichClipboard);</code></td> </tr> <tr> <td><code>void <a href="#setData()">setData</a>(in nsITransferable aTransferable, in nsIClipboardOwner anOwner, in long aWhichClipboard);</code></td> </tr> <tr> <td><code>boolean <a href="#supportsSelectionClipboard()">supportsSelectionClipboard</a>();</code></td> </tr> </tbody> +</table> +<h2 id="Constants" name="Constants">常量</h2> +<p>Most users will expect clipboard operations to use the global clipboard. In fact, the <code>kSelectionClipboard</code> is peculiar to the X Windows System, and not used much even under X.</p> +<table class="standard-table"> <tbody> <tr> <td class="header">常量名称</td> <td class="header">值</td> <td class="header">描述</td> </tr> <tr> <td><code>kSelectionClipboard</code></td> <td><code>0</code></td> <td>Clipboard for selection.</td> </tr> <tr> <td><code>kGlobalClipboard</code></td> <td><code>1</code></td> <td>Clipboard for global use.</td> </tr> </tbody> +</table> +<h2 id="Methods" name="Methods">方法</h2> +<h3 id="emptyClipboard()" name="emptyClipboard()">emptyClipboard()</h3> +<p>This method empties the clipboard and notifies the clipboard owner. It empties the "logical" clipboard. It does not clear the native clipboard.</p> +<pre class="eval">void emptyClipboard( + in long aWhichClipboard +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> <dt><code>aWhichClipboard</code></dt> <dd>Specifies the clipboard to which this operation applies.</dd> +</dl> +<p></p><div class="headingWithIndicator"> + <h3 id="forceDataToClipboard()">forceDataToClipboard()</h3> + <span class="indicatorInHeadline obsolete obsoleteMethod">已废弃 Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)</span> + </div><p></p> +<p>Some platforms support deferred notification for putting data on the clipboard This method forces the data onto the clipboard in its various formats This may be used if the application going away.</p> +<pre class="eval">void forceDataToClipboard( + in long aWhichClipboard +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> <dt><code>aWhichClipboard</code></dt> <dd>Specifies the clipboard to which this operation applies.</dd> +</dl> +<h3 id="getData()" name="getData()">getData()</h3> +<p>This method retrieves data from the clipboard into a transferable.</p> +<pre class="eval">void getData( + in nsITransferable aTransferable, + in long aWhichClipboard +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> <dt><code>aTransferable</code></dt> <dd>The transferable to receive data from the clipboard.</dd> <dt><code>aWhichClipboard</code></dt> <dd>Specifies the clipboard to which this operation applies.</dd> +</dl> +<h3 id="hasDataMatchingFlavors()" name="hasDataMatchingFlavors()">hasDataMatchingFlavors()</h3> +<p>This method provides a way to give correct UI feedback about, for instance, whether a paste should be allowed. It does <strong>not</strong> actually retrieve the data and should be a very inexpensive call. All it does is check if there is data on the clipboard matching any of the flavors in the given list.</p> +<pre class="eval">boolean hasDataMatchingFlavors( + [array, size_is(aLength)] in string aFlavorList, + in unsigned long aLength, + in long aWhichClipboard +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> <dt><code>aFlavorList</code></dt> <dd>An array of ASCII strings.</dd> <dt><code>aLength</code></dt> <dd>The length of the <code>aFlavorList</code>.</dd> <dt><code>aWhichClipboard</code></dt> <dd>Specifies the clipboard to which this operation applies.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<p>Returns <code>true</code>, if data is present and it matches the specified flavor. Otherwise it returns <code>false</code>.</p> +<h3 id="setData()" name="setData()">setData()</h3> +<p>This method sets the data from a transferable on the native clipboard.</p> +<pre class="eval">void setData( + in nsITransferable aTransferable, + in nsIClipboardOwner anOwner, + in long aWhichClipboard +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> <dt><code>aTransferable</code></dt> <dd>The transferable containing the data to put on the clipboard.</dd> <dt><code>anOwner</code></dt> <dd>The owner of the transferable.</dd> <dt><code>aWhichClipboard</code></dt> <dd>Specifies the clipboard to which this operation applies.</dd> +</dl> +<h3 id="supportsSelectionClipboard()" name="supportsSelectionClipboard()">supportsSelectionClipboard()</h3> +<p>This method allows clients to determine if the implementation supports the concept of a separate clipboard for selection.</p> +<pre class="eval">boolean supportsSelectionClipboard(); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">返回值</h6> +<p>Returns <code>true</code> if <code>kSelectionClipboard</code> is available. Otherwise it returns <code>false</code>.</p> +<h2 id="See_also" name="See_also">相关链接</h2> +<ul> <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboardOwner" title="">nsIClipboardOwner</a></code></li> <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsITransferable" title="">nsITransferable</a></code></li> <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIArray" title="">nsIArray</a></code></li> <li><a class="internal" href="/zh-cn/Using_the_Clipboard" title="Using the Clipboard">Using the Clipboard</a></li> +</ul> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiclipboardhelper/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiclipboardhelper/index.html new file mode 100644 index 0000000000..b4c7881597 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiclipboardhelper/index.html @@ -0,0 +1,65 @@ +--- +title: nsIClipboardHelper +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboardHelper +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboardHelper +--- +<div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/widget/public/nsIClipboardHelper.idl" rel="custom">widget/public/nsIClipboardHelper.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +<code>nsIClipboardHelper接口是能够快速方便的使用</code> nsIClipboard 接口中常用方法的辅助接口. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.7 </span></div> +</div> +<h2 id="Method_overview" name="Method_overview">方法概述</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#copyString()">copyString</a>(in AString aString);</code></td> + </tr> + <tr> + <td><code>void <a href="#copyStringToClipboard()">copyStringToClipboard</a>(in AString aString, in long aClipboardID);</code></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">方法</h2> +<h3 id="copyString()" name="copyString()">copyString()</h3> +<p>该方法将字符串复制到默认剪切板.</p> +<pre class="eval">void copyString( + in AString aString +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aString</code></dt> + <dd> + 将要复制到剪切板的字符串.</dd> +</dl> +<h3 id="copyStringToClipboard()" name="copyStringToClipboard()">copyStringToClipboard()</h3> +<p>该方法将字符串复制到指定剪切板.</p> +<pre class="eval">void copyStringToClipboard( + in AString aString, + in long aClipboardID +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aString</code></dt> + <dd> + 将要复制到指定剪切板的字符串.</dd> + <dt> + <code>aClipboardID</code></dt> + <dd> + 指定剪切板的ID(例如<code>kSelectionClipboard</code>).</dd> +</dl> +<h2 id="See_also" name="See_also">相关连接</h2> +<ul> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIClipboard" title="">nsIClipboard</a></code></li> + <li><a href="/zh-cn/Using_the_Clipboard" title="zh-cn/Using the Clipboard">Using the Clipboard</a></li> +</ul> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiconsoleservice/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiconsoleservice/index.html new file mode 100644 index 0000000000..b373505057 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiconsoleservice/index.html @@ -0,0 +1,215 @@ +--- +title: nsIConsoleService +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleService +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleService +--- +<div class="warning"> + <p>Error Console在Firefox中已经过期,只有将<code>devtools.errorconsole.enabled<font face="Open Sans, sans-serif"><span style="line-height: 23.33333396911621px;"> + <i> + 设为</i> + </span></font></code><code>true<em>才能使用</em></code>. 对于web应用使用 <a href="/en-US/docs/Tools/Web_Console" title="/en-US/docs/Tools/Web_Console">Web Console </a>代替, 对于浏览器中的chrome应用，使用 <a href="/en-US/docs/Tools/Browser_Console" title="/en-US/docs/Tools/Browser_Console">Browser Console</a> 代替 .</p> +</div> +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/xpcom/base/nsIConsoleService.idl" rel="custom">xpcom/base/nsIConsoleService.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +console service是<a title="en/Error_Console">Error Console</a> 后端的一部分, 与每一个Mozilla应用绑定在一起. 它用来记录各种消息、警告以及错误,同时可获取所有已经记录的消息 +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.9 (Firefox 3)</span></div> +</div><p></p> +<p>实现方式: <code>@mozilla.org/consoleservice;1</code> as a service:</p> +<pre class="eval">var consoleService = Components.classes["@mozilla.org/consoleservice;1"] + .getService(Components.interfaces.nsIConsoleService); +</pre> +<h2 id="Method_overview" name="Method_overview">Method overview</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#getMessageArray()">getMessageArray</a>([array, size_is(count)] out nsIConsoleMessage messages, out uint32_t count);</code><span class="inlineIndicator obsolete obsoleteInline" title="(Firefox 19 / Thunderbird 19 / SeaMonkey 2.16)">已废弃 Gecko 19</span><br> + <code>void <a href="#getMessageArray()">getMessageArray</a>(</code><code>[optional] out uint32_t count, </code><code>[retval, array, size_is(count)] out nsIConsoleMessage messages);</code></td> + </tr> + <tr> + <td><code>void <a href="#logMessage()">logMessage</a>(in nsIConsoleMessage message);</code></td> + </tr> + <tr> + <td><code>void <a href="#logStringMessage()">logStringMessage</a>(in wstring message);</code></td> + </tr> + <tr> + <td><code>void <a href="#registerListener()">registerListener</a>(in nsIConsoleListener listener);</code></td> + </tr> + <tr> + <td><code>void <a href="#reset()">reset</a>();</code> </td> + </tr> + <tr> + <td><code>void <a href="#unregisterListener()">unregisterListener</a>(in nsIConsoleListener listener);</code></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">Methods</h2> +<h3 id="getMessageArray()" name="getMessageArray()">getMessageArray()</h3> +<p>获取有关目前所有控制台记录的信息的数组</p> +<p></p><div class="blockIndicator obsolete obsoleteHeader"><p><strong><span class="icon-only-inline" title="This is an obsolete API and is no longer guaranteed to work."><i class="icon-trash"> </i></span> 已废弃 Gecko 19 (Firefox 19 / Thunderbird 19 / SeaMonkey 2.16)</strong><br>This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.</p></div><p></p> +<pre class="eval">void getMessageArray( + [array, size_is(count)] out nsIConsoleMessage messages, + out PRUint32 count +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>messages</code></dt> + <dd> + 已经记录的消息数组</dd> + <dt> + <code>count</code></dt> + <dd> + 数组中消息的数。如果没有消息被记录，函数会返回0，但同时仍会为message分配一个标记，在从脚本调用时，表示返回的一个长度为0的消息。</dd> +</dl> +<p></p> +<pre class="eval">void getMessageArray( + [optional] out PRUint32 count, + [retval, array, size_is(count)] out nsIConsoleMessage messages +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>count</code></dt> + <dd> + The number of messages in the array. If no messages are logged, this function will return a count of 0 but still will allocate one word for messages, so as to show up as a 0-length array when called from script.</dd> +</dl> +<p></p><div class="blockIndicator note"><strong>Note:</strong> See the code samples below for how to call getMessageArray.</div><p></p> +<h3 id="logMessage()" name="logMessage()">logMessage()</h3> +<pre class="eval">void logMessage( + in nsIConsoleMessage message +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>message</code></dt> + <dd> + An <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleMessage" title="">nsIConsoleMessage</a></code> to log.</dd> +</dl> +<h3 id="logStringMessage()" name="logStringMessage()">logStringMessage()</h3> +<p>Convenience method for logging simple messages.</p> +<pre class="eval">void logStringMessage( + in wstring message +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>message</code></dt> + <dd> + The string to log.</dd> +</dl> +<h3 id="registerListener()" name="registerListener()">registerListener()</h3> +<p>Registers a listener for notification when an error is logged.</p> +<p></p><div class="blockIndicator note"><strong>Note:</strong> To guard against stack overflows from listeners that could log messages (it is easy to do this inadvertently from listeners implemented in JavaScript), we do not call any listeners when another error is already being logged.</div><p></p> +<pre class="eval">void registerListener( + in nsIConsoleListener listener +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>listener</code></dt> + <dd> + The <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleListener" title="">nsIConsoleListener</a></code> to add.</dd> +</dl> +<p></p><h3 id="reset()">reset()</h3><p></p> +<p>Clear the message buffer (For example, for privacy reasons).</p> +<pre class="eval">void reset(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<p></p><div class="blockIndicator note"><strong>Note:</strong> Console listeners expect you to log an empty string message before calling <code>reset</code> so that they can clear their message buffers too. (This works before Gecko 1.9 too of course.)</div><p></p> +<h3 id="unregisterListener()" name="unregisterListener()">unregisterListener()</h3> +<p>Unregisters a listener.</p> +<pre class="eval">void unregisterListener( + in nsIConsoleListener listener +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>listener</code></dt> + <dd> + The <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleListener" title="">nsIConsoleListener</a></code> to remove.</dd> +</dl> +<h2 id="Examples" name="Examples">Examples</h2> +<h4 id="Retrieving_the_message_array" name="Retrieving_the_message_array">Retrieving the message array</h4> +<p>To retrieve the message array in Gecko prior to version 19:</p> +<pre class="brush: js">function getConsoleMessageArray() { + var consoleService = Components.classes["@mozilla.org/consoleservice;1"] + .getService(Components.interfaces.nsIConsoleService); + var array = {}; + consoleService.getMessageArray(array, {}); + return array.value; +} +</pre> +<p>To retrieve the message array in Gecko 19 or later:</p> +<pre class="brush: js">function getConsoleMessageArray() { + var consoleService = Components.classes["@mozilla.org/consoleservice;1"] + .getService(Components.interfaces.nsIConsoleService); + return consoleService.getMessageArray(); +} +</pre> +<p>To retrieve the message array in a compatible way:</p> +<pre class="brush: js">function getConsoleMessageArray() { + var consoleService = Components.classes["@mozilla.org/consoleservice;1"] + .getService(Components.interfaces.nsIConsoleService); + var array = {}; + return consoleService.getMessageArray(array, {}) || array.value; +} +</pre> +<h4 id="Logging_a_simple_message" name="Logging_a_simple_message">Logging a simple message</h4> +<p>A common usage is to log a string message to console:</p> +<pre class="brush: js">function LOG(msg) { + var consoleService = Components.classes["@mozilla.org/consoleservice;1"] + .getService(Components.interfaces.nsIConsoleService); + consoleService.logStringMessage(msg); +} +</pre> +<p>Alternative logging methods include <a href="/en/Components.utils.reportError" title="en/Components.utils.reportError">Components.utils.reportError</a> and <a href="/en/DOM/window.dump" title="en/DOM/window.dump">dump()</a>.</p> +<h4 id="Logging_a_message_with_additional_information" name="Logging_a_message_with_additional_information">Logging a message with additional information</h4> +<p>To include other information an <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleMessage" title="">nsIConsoleMessage</a></code> object must be used. In this example <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIScriptError" title="">nsIScriptError</a></code>, which implements <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleMessage" title="">nsIConsoleMessage</a></code>, is used to include information about the source file and line number of the error.</p> +<pre class="brush: js">function myLogToConsole(aMessage, aSourceName, aSourceLine, aLineNumber, + aColumnNumber, aFlags, aCategory) +{ + var consoleService = Components.classes["@mozilla.org/consoleservice;1"] + .getService(Components.interfaces.nsIConsoleService); + var scriptError = Components.classes["@mozilla.org/scripterror;1"] + .createInstance(Components.interfaces.nsIScriptError); + scriptError.init(aMessage, aSourceName, aSourceLine, aLineNumber, + aColumnNumber, aFlags, aCategory); + consoleService.logMessage(scriptError); +} +</pre> +<ul> + <li><code>aMessage</code> — the string to be logged. You must provide this.</li> + <li><code>aSourceName</code> — the URL of file with error. This will be a hyperlink in the Error Console, so you'd better use real URL. You may pass <code>null</code> if it's not applicable.</li> + <li><code>aSourceLine</code> — the line #<code>aLineNumber</code> from <code>aSourceName</code> file. You are responsible for providing that line. You may pass <code>null</code> if you are lazy; that will prevent showing the source line in Error Console.</li> + <li><code>aLineNumber</code> and <code>aColumnNumber</code> — specify the exact location of error. <code>aColumnNumber</code> is used to draw the arrow pointing to the problem character.</li> + <li><code>aFlags</code> — one of flags declared in <code>nsIScriptError</code>. At the time of writing, possible values are: + <ul> + <li><code>nsIScriptError.errorFlag = 0</code></li> + <li><code>nsIScriptError.warningFlag = 1</code></li> + <li><code>nsIScriptError.exceptionFlag = 2</code> and</li> + <li><code>nsIScriptError.strictFlag = 4</code>.</li> + </ul> + </li> + <li><code>aCategory</code> — a string indicating what kind of code caused the message. There are quite a few category strings and they do not seem to be listed in a single place. Hopefully, they will all be listed in <code>nsIScriptError.idl</code> eventually.</li> +</ul> +<h2 id="See_also" name="See_also">See also</h2> +<ul> + <li><a href="/en/Error_Console" title="en/Error_Console">Error Console</a></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIConsoleMessage" title="">nsIConsoleMessage</a></code></li> +</ul> +<p></p> +<div id="cke_pastebin" style="position: absolute; top: 894.333px; width: 1px; height: 1px; overflow: hidden; left: -1000px;"> + </div> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsidirectoryserviceprovider/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsidirectoryserviceprovider/index.html new file mode 100644 index 0000000000..20d094eaf3 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsidirectoryserviceprovider/index.html @@ -0,0 +1,65 @@ +--- +title: nsIDirectoryServiceProvider +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIDirectoryServiceProvider +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIDirectoryServiceProvider +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/xpcom/io/nsIDirectoryService.idl" rel="custom">xpcom/io/nsIDirectoryService.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +本接口是目录服务用于得到文件位置的函数。 +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.7 </span></div> +</div><p></p> +<p><code>nsIDirectoryServiceProvider</code>.</p> +<h2 id="Method_overview" name="Method_overview">方法概览</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>nsIFile <a href="#getFile()">getFile</a>(in string prop, out PRBool persistent);</code></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">方法</h2> +<h3 id="getFile()" name="getFile()">getFile()</h3> +<p>The Directory Service calls this method when it gets the first request for a prop or on every request if the prop is not persistent.</p> +<pre class="eval">nsIFile getFile( + in string prop, + out PRBool persistent +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>prop</code></dt> + <dd> + The symbolic name of the file.</dd> + <dt> + <code>persistent</code></dt> + <dd> + <code>true</code> if the returned file will be cached by Directory Service. Subsequent requests for this prop will bypass the provider and use the cache. <code>false</code> if the provider will be asked for this prop each time it is requested.</dd> +</dl> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p>The <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code> represented by the property.</p> +<h2 id="Example" name="Example">示例</h2> +<p>This code creates a global, read-only string called <code>currDir</code> with the value of the current working directory.</p> +<pre class="eval"> __defineGetter__("currDir", + function getCurrDir() { + return Components.classes["@mozilla.org/file/directory_service;1"] + .getService(Components.interfaces.nsIDirectoryServiceProvider) + .getFile("CurWorkD",{}).path; + }); +</pre> +<p>Test it with to see the magic happen.</p> +<pre class="eval"> alert(currDir); +</pre> +<h2 id="See_also" name="See_also">参见</h2> +<ul> + <li><a href="/en/nsDirectoryService" title="en/nsDirectoryService">nsDirectoryService</a></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDirectoryService" title="">nsIDirectoryService</a></code></li> + <li>（译注）其它目录服务关键字见<a href="http://mxr.mozilla.org/mozilla-central/source/xpcom/io/nsDirectoryServiceDefs.h" title="http://mxr.mozilla.org/mozilla-central/source/xpcom/io/nsDirectoryServiceDefs.h">nsDirectoryServiceDefs.h</a></li> +</ul> +<p>Additionally, see <a class="external" href="http://mb.eschew.org/16.php#sub_16.5.2">section 16.5.2</a> of the <a class="external" href="http://mb.eschew.org/">Rapid Application Development with Mozilla</a> book for instructions on how to get the <strong>current working directory</strong> and the <strong>process binary directory</strong>, among other things.</p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsidomclientrect/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsidomclientrect/index.html new file mode 100644 index 0000000000..20a00c9e26 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsidomclientrect/index.html @@ -0,0 +1,92 @@ +--- +title: nsIDOMClientRect +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMClientRect +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMClientRect +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/dom/interfaces/base/nsIDOMClientRect.idl" rel="custom">dom/interfaces/base/nsIDOMClientRect.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;">代表一个矩形盒子。盒子类型由返回这种盒子对象的方法指定的。它是由像<a href="/zh-CN/docs/Web/API/Element/getBoundingClientRect" title="Element.getBoundingClientRect()方法返回元素的大小及其相对于视口的位置。"><code>element.getBoundingClientRect</code></a>的函数返回的。.</span> + + <div style="height: 42px; position: relative; padding: 2px; width: auto;"> + + <div style="top: 22px; font-size: 11px; position: absolute;">1.0</div> + + <div style="top: 22px; font-size: 11px; position: absolute; left: 0px; text-align: right; float: right; width: 100%;">66</div> + + <div style="height: 8px; top: 16px; background: #dd0000; left: 0px; position: absolute; width: 8.571428571428571%;"></div> + +<div style="height: 8px; top: 16px; left: 8.571428571428571%; background: #00dd00; position: absolute; width: 91.42857142857143%;" title="Introduced in Gecko 1.9 (Firefox 3)"></div> + +<div style="top: 0px; font-size: 11px; position: absolute; left: 8.571428571428571%;">Introduced</div> +<div style="top: 22px; font-size: 11px; position: absolute; left: 8.571428571428571%;">Gecko 1.9</div> + + <div style="height: 8px; top: 16px; left: 9.023809428571429%; background: #eeee00; position: absolute; width: 1%; border-radius: 4px; -webkit-border-radius: 4px;" title="Last changed in Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)"></div> + +</div> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)</span></div> +</div><p></p> + +<h2 id="Attributes" name="Attributes">属性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Attribute</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>bottom</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>Y 轴，相对于视口原点（viewport origin）矩形盒子的底部。<strong>只读。 </strong></td> + </tr> + <tr> + <td><code>height</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>矩形盒子的高度（等同于 bottom 减 top）。<strong>只读。</strong></td> + </tr> + <tr> + <td><code>left</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>X 轴，相对于视口原点（viewport origin）矩形盒子的左侧。<strong>只读。 </strong></td> + </tr> + <tr> + <td><code>right</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>X 轴，相对于视口原点（viewport origin）矩形盒子的右侧。<strong>只读。 </strong></td> + </tr> + <tr> + <td><code>top</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>Y 轴，相对于视口原点（viewport origin）矩形盒子的顶部。<strong>只读。</strong></td> + </tr> + <tr> + <td><code>width</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>矩形盒子的宽度（等同于 right 减 left）。<strong>只读。</strong> </td> + </tr> + <tr> + <td><code>x</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>X 轴，相对于视口原点（viewport origin）矩形盒子的左侧。<strong>只读。</strong> </td> + </tr> + <tr> + <td><code>y</code></td> + <td><code><a href="/en/float" title="en/float">float</a></code></td> + <td>Y 轴，相对于视口原点（viewport origin）矩形盒子的顶部。<strong>只读。</strong></td> + </tr> + </tbody> +</table> + +<h2 id="See_also" name="See_also">参考资料</h2> + +<ul> + <li><a href="http://www.w3.org/TR/cssom-view/#the-clientrect-interface">CSSOM View Module : The ClientRect Interface</a><span style="color: #fff; background: #e66e33; display: inline-block; font-size: x-small; margin-left: 6px; white-space: nowrap; padding: 2px 5px;" title="工作草案">WD</span></li> +</ul> + +<p><span style="line-height: 1.5;">这个对象几次易名：最初叫做 TextRectangle，</span><a href="https://bugzilla.mozilla.org/show_bug.cgi?id=916520" style="line-height: 1.5;">然后</a><span style="line-height: 1.5;">叫做 ClientRect，</span><a href="https://bugzilla.mozilla.org/show_bug.cgi?id=916520" style="line-height: 1.5;">后来</a><span style="line-height: 1.5;">叫做 DOMRect。</span></p> + +<p><span style="line-height: 1.5;">该对象最初只有 top、left、right、bottom 属性，后来添加了 width、height、x、y 属性。</span></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsifile/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsifile/index.html new file mode 100644 index 0000000000..d966771e83 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsifile/index.html @@ -0,0 +1,828 @@ +--- +title: nsIFile +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIFile +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIFile +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/xpcom/io/nsIFile.idl" rel="custom">xpcom/io/nsIFile.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +An instance of this interface is a cross-platform representation of a location in the filesystem. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.0 </span></div> +</div><p></p> +<p><code>nsIFile</code> is the correct platform-agnostic way to specify a file; you should always use this instead of a string to ensure compatibility.</p> +<p>With an <code>nsIFile</code> you can navigate to ancestors or descendants without having to deal with the different path separators used on different platforms, query the state of any file or directory at the position represented by the <code>nsIFile</code> and create, move or copy items in the filesystem.</p> +<p>An <code>nsIFile</code> can be retrieved by either instantiating an <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile" title="">nsILocalFile</a></code> using a platform specific path string or by using cross-platform locations retrieved from the <a href="/en/Code_snippets/File_I//O#Getting_special_files" title="en/Code_snippets/File_I//O#Getting_special_files">directory service</a>.</p> +<p>All methods with string parameters have two forms. The preferred form operates on UTF-16 encoded characters strings. An alternate form operates on characters strings encoded in the "native" charset. A string containing characters encoded in the native charset cannot be safely passed to javascript via xpconnect. Therefore, the UTF-16 forms are scriptable, but the "native methods" are not. In addition, the native form <strong>cannot</strong> deal with files whose name contains characters outside the default system code page on Windows. Using the native form limits the ability of your code to deal with the full Unicode support on Windows 2000 or later where the OS itself does not have such a limitation. Therefore, you <strong>must not</strong> use the native form unless it is <strong>guaranteed</strong> that the path passed to a native form function is <strong>always</strong> ASCII.</p> +<div class="note"> + <strong>Note:</strong> <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile" title="">nsILocalFile</a></code> was merged with this interface in Gecko 14. Much of the documentation has not been updated to reflect this change.</div> +<h2 id="Method_overview" name="Method_overview">Method overview</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#append()">append</a>(in AString node);</code></td> + </tr> + <tr> + <td><code>void <a href="#appendNative()">appendNative</a>(in ACString node);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#appendRelativeNativePath()" title="/en/XPCOM_Interface_Reference/nsILocalFile#appendRelativeNativePath()">appendRelativeNativePath</a>(in ACString relativeFilePath);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#appendRelativePath()" title="/en/XPCOM_Interface_Reference/nsILocalFile#appendRelativePath()">appendRelativePath</a>(in AString relativeFilePath);</code> </td> + </tr> + <tr> + <td><code>nsIFile <a href="#clone()">clone</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#contains()">contains</a>(in nsIFile inFile, in boolean recur);</code></td> + </tr> + <tr> + <td><code>void <a href="#copyTo()">copyTo</a>(in nsIFile newParentDir, in AString newName);</code></td> + </tr> + <tr> + <td><code>void <a href="#copyToFollowingLinks()">copyToFollowingLinks</a>(in nsIFile newParentDir, in AString newName);</code></td> + </tr> + <tr> + <td><code>void <a href="#copyToFollowingLinksNative()">copyToFollowingLinksNative</a>(in nsIFile newParentDir, in ACString newName);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#CopyToNative()">CopyToNative</a>(in nsIFile newParentDir, in ACString newName);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#create()">create</a>(in unsigned long type, in unsigned long permissions);</code></td> + </tr> + <tr> + <td><code>void <a href="#createUnique()">createUnique</a>(in unsigned long type, in unsigned long permissions);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#equals()">equals</a>(in nsIFile inFile);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#exists()">exists</a>();</code></td> + </tr> + <tr> + <td><code>ACString <a href="/en/XPCOM_Interface_Reference/nsILocalFile#getRelativeDescriptor()" title="/en/XPCOM_Interface_Reference/nsILocalFile#getRelativeDescriptor()">getRelativeDescriptor</a>(in nsIFile fromFile);</code> </td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#initWithFile()" title="/en/XPCOM_Interface_Reference/nsILocalFile#initWithFile()">initWithFile</a>(in nsIFile aFile);</code> </td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#initWithNativePath()" title="/en/XPCOM_Interface_Reference/nsILocalFile#initWithNativePath()">initWithNativePath</a>(in ACString filePath);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#initWithPath()" title="/en/XPCOM_Interface_Reference/nsILocalFile#initWithPath()">initWithPath</a>(in AString filePath);</code> </td> + </tr> + <tr> + <td><code>boolean <a href="#isDirectory()">isDirectory</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isExecutable()">isExecutable</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isFile()">isFile</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isHidden()">isHidden</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isReadable()">isReadable</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isSpecial()">isSpecial</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isSymlink()">isSymlink</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isWritable()">isWritable</a>();</code></td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#launch()" title="/en/XPCOM_Interface_Reference/nsILocalFile#launch()">launch</a>();</code> </td> + </tr> + <tr> + <td><code>PRLibraryStar <a href="/en/XPCOM_Interface_Reference/nsILocalFile#load()" title="/en/XPCOM_Interface_Reference/nsILocalFile#load()">load</a>();</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#moveTo()">moveTo</a>(in nsIFile newParentDir, in AString newName);</code></td> + </tr> + <tr> + <td><code>void <a href="#moveToNative()">moveToNative</a>(in nsIFile newParentDir, in ACString newName);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#normalize()">normalize</a>();</code></td> + </tr> + <tr> + <td><code>FILE <a href="/en/XPCOM_Interface_Reference/nsILocalFile#openANSIFileDesc()" title="/en/XPCOM_Interface_Reference/nsILocalFile#openANSIFileDesc()">openANSIFileDesc</a>(in string mode);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>PRFileDescStar <a href="/en/XPCOM_Interface_Reference/nsILocalFile#openNSPRFileDesc()" title="/en/XPCOM_Interface_Reference/nsILocalFile#openNSPRFileDesc()">openNSPRFileDesc</a>(in long flags, in long mode);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#remove()">remove</a>(in boolean recursive);</code></td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#reveal()" title="/en/XPCOM_Interface_Reference/nsILocalFile#reveal()">reveal</a>();</code> </td> + </tr> + <tr> + <td><code>void <a href="/en/XPCOM_Interface_Reference/nsILocalFile#setRelativeDescriptor()" title="/en/XPCOM_Interface_Reference/nsILocalFile#setRelativeDescriptor()">setRelativeDescriptor</a>(in nsIFile fromFile, in ACString relativeDesc);</code> </td> + </tr> + </tbody> +</table> +<h2 id="Attributes" name="Attributes">Attributes</h2> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Attribute</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>directoryEntries</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISimpleEnumerator" title="">nsISimpleEnumerator</a></code></code></td> + <td>Returns an enumeration of the elements in a directory. Each element in the enumeration is an <code>nsIFile</code>. <strong>Read only.</strong> + <h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + <dl> + <dt> + <code>NS_ERROR_FILE_NOT_DIRECTORY</code></dt> + <dd> + Indicates that this <code>nsIFile</code> does not reference a directory.</dd> + </dl> + </td> + </tr> + <tr> + <td><code>diskSpaceAvailable</code> </td> + <td><code><a href="/en/PRInt64" title="en/PRInt64">PRInt64</a></code></td> + <td>The number of bytes available to non-superuser on the disk volume containing the <code>nsIFile</code>. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>fileSize</code></td> + <td><code><a href="/en/PRInt64" title="en/PRInt64">PRInt64</a></code></td> + <td> + <p>The value of this attribute is the number of bytes corresponding to the data represented by the file.</p> + <p>On the Mac, getting/setting the file size with <code>nsIFile</code> only deals with the size of the data fork. If you need to know the size of the combined data and resource forks use <code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsILocalFileMac#GetFileSizeWithResFork()">nsILocalFileMac.GetFileSizeWithResFork()</a></code>.</p> + Changing the size of a <code>nsIFile</code> operates on the underlying filesystem, possibly truncating the existing file to specified size.</td> + </tr> + <tr> + <td><code>fileSizeOfLink</code></td> + <td><code><a href="/en/PRInt64" title="en/PRInt64">PRInt64</a></code></td> + <td> + <p>This attribute exposes the size of the symbolic link referenced by this <code>nsIFile</code>.</p> + <p>Unlike <code>fileSize</code>, this attribute corresponds to the size of the symbolic link referenced by this <code>nsIFile</code>. If this <code>nsIFile</code> does not reference a symbolic link, then the value of this attribute is undefined.</p> + The value of this attribute is the number of bytes corresponding to the data represented by the symbolic link. Any meta data, such as a resource fork on the Mac, is not included in the measurement of the file size. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>followLinks</code> </td> + <td><code><a href="/en/PRBool" title="en/PRBool">PRBool</a></code></td> + <td> + <p>Determines whether or not the <code>nsIFile</code> will automatically resolve symbolic links.</p> + By default, this value is <code>false</code> on all non-UNIX systems. As of Mozilla 1.7, this attribute is ignored on UNIX systems.</td> + </tr> + <tr> + <td><code>lastModifiedTime</code></td> + <td><code><a href="/en/PRInt64" title="en/PRInt64">PRInt64</a></code></td> + <td> + <p>This attribute exposes the time when the file referenced by this <code>nsIFile</code> was last modified.</p> + <p>The value of this attribute is milliseconds since midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).</p> + Changing the last modified time of a <code>nsIFile</code> operates on the underlying filesystem. As of <span title="">Gecko 1.7</span>, changing the last modified time of a non-existent file has undefined behavior.</td> + </tr> + <tr> + <td><code>lastModifiedTimeOfLink</code></td> + <td><code><a href="/en/PRInt64" title="en/PRInt64">PRInt64</a></code></td> + <td> + <p>This attribute exposes the time when the symbolic link referenced by this <code>nsIFile</code> was last modified.</p> + <p>Unlike <code>lastModifiedTime</code>, this attribute corresponds to the last modified time of the symbolic link referenced by this <code>nsIFile</code>. If this <code>nsIFile</code> does not reference a symbolic link, then the value of this attribute is undefined.</p> + <p>The value of this attribute is milliseconds since midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).</p> + Changing the last modified time of a <code>nsIFile</code> operates on the underlying filesystem. As of <span title="">Gecko 1.7</span>, changing the last modified time of a non-existent file has undefined behavior.</td> + </tr> + <tr> + <td><code>leafName</code></td> + <td><code><a href="/en/AString" title="en/AString">AString</a></code></td> + <td> + <p>This attribute exposes the name of the <code>nsIFile</code> without any directory components.</p> + Changing the leaf name of a <code>nsIFile</code> does not affect the underlying filesystem. It only changes what this <code>nsIFile</code> references.</td> + </tr> + <tr> + <td><code>nativeLeafName</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a></code></td> + <td> + <p>This attribute exposes the name of the <code>nsIFile</code> without any directory components. [native character encoding variant]</p> + Changing the leaf name of a <code>nsIFile</code> does not affect the underlying filesystem. It only changes what this <code>nsIFile</code> references. <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>nativePath</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a></code></td> + <td> + <p>This attribute exposes the full path of the <code>nsIFile</code>. [native character encoding variant]</p> + The value of this attribute is a platform-specific file path. <strong>Read only.</strong> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>nativeTarget</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a></code></td> + <td> + <p>This attribute exposes the full target of the <code>nsIFile</code> - the full path with any symbolic links dereferenced. [native character encoding variant]</p> + The value of this attribute is a platform-specific file path. <strong>Read only.</strong> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>parent</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code></code></td> + <td> + <p>This attribute returns the parent <code>nsIFile</code> for this <code>nsIFile</code>.</p> + The parent will be <code>null</code> when this <code>nsIFile</code> references the top of the volume. For example, C:\ does not have a parent. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>path</code></td> + <td><code><a href="/en/AString" title="en/AString">AString</a></code></td> + <td> + <p>This attribute exposes the full platform-specific path of the <code>nsIFile</code> (including the <code>leafName</code>). <strong>Read only.</strong></p> + Example, this could return "/home/user/foo.txt" or "C:\Images\my.jpeg"</td> + </tr> + <tr> + <td><code>permissions</code></td> + <td><code><a href="/en/unsigned_long" title="en/unsigned long">unsigned long</a></code></td> + <td> + <p>The value of this attribute is a UNIX-style file permission mask for this <code>nsIFile</code>.</p> + Changing the permissions of a <code>nsIFile</code> operates on the underlying filesystem. As of <span title="">Gecko 1.7</span>, changing the permissions of a non-existent file has undefined behavior.</td> + </tr> + <tr> + <td><code>permissionsOfLink</code></td> + <td><code><a href="/en/unsigned_long" title="en/unsigned long">unsigned long</a></code></td> + <td> + <p>The value of this attribute is a UNIX-style file permission mask for this <code>nsIFile</code>.</p> + <p>Unlike <code>permissions</code>, this attribute corresponds to the permissions of the symbolic link referenced by this <code>nsIFile</code>. If this <code>nsIFile</code> does not reference a symbolic link, then the value of this attribute is undefined.</p> + Changing the permissions of a <code>nsIFile</code> operates on the underlying filesystem. As of <span title="">Gecko 1.7</span>, changing the permissions of a non-existent file has undefined behavior.</td> + </tr> + <tr> + <td><code>persistentDescriptor</code> </td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a></code></td> + <td> + <p>On some platforms, the value of <a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIFile#path">nsIFile.path</a> may be insufficient to uniquely identify the file on the local file system. The persistent descriptor is intended to be used whenever a <code>nsIFile</code> needs to be serialized to disk and later recovered. This string is not intended for display to users.</p> + <div class="blockIndicator note"><strong>Note:</strong> The value of the <code>followLinks</code> attribute is not encoded in the persistent descriptor.</div></td> + </tr> + <tr> + <td><code>target</code></td> + <td><code><a href="/en/AString" title="en/AString">AString</a></code></td> + <td> + <p>This attribute exposes the full target of the <code>nsIFile</code> - the full path with any symbolic links dereferenced.</p> + <p>Accessor to the string <code>path</code>. The native version of these strings are not guaranteed to be a usable <code>path</code> to pass to NSPR or the C stdlib. There are problems that affect platforms on which a <code>path</code> does not fully specify a file because two volumes can have the same name (For example Mac). This is solved by holding "private", native data in the <code>nsIFile</code> implementation. This native data is lost when you convert to a string. DO NOT PASS TO USE WITH NSPR OR STDLIB! <strong>Read only.</strong></p> + <h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + <dl> + <dt> + <code>NS_ERROR_FILE_INVALID_PATH</code></dt> + <dd> + Indicates that this <code>nsIFile</code> does not reference a symbolic links.</dd> + </dl> + </td> + </tr> + </tbody> +</table> +<h2 id="Constants" name="Constants">Constants</h2> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>NORMAL_FILE_TYPE</code></td> + <td><code>0</code></td> + <td>A normal file.</td> + </tr> + <tr> + <td><code>DIRECTORY_TYPE</code></td> + <td><code>1</code></td> + <td>A directory/folder.</td> + </tr> + <tr> + <td><code>DELETE_ON_CLOSE</code> </td> + <td><code>0x80000000</code></td> + <td>Optional parameter used by <a href="/en/XPCOM_Interface_Reference/nsILocalFile#openNSPRFileDesc()" title="/en/XPCOM_Interface_Reference/nsILocalFile#openNSPRFileDesc()">openNSPRFileDesc</a></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">Methods</h2> +<h3 id="append()" name="append()">append()</h3> +<p>This function is used for constructing a descendant of the current <code>nsIFile</code>.</p> +<div class="note style-wrap"> + <p><strong>Note:</strong> This method does not return a new <code>nsIFile</code>; it modifies the object it was called on. If the old <code>nsIFile</code> should be retained, use <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile#clone()">clone()</a></code>.</p> +</div> +<pre class="eval">void append( + in AString node +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>node</code></dt> + <dd> + A string which is intended to be a child node of the <code>nsIFile</code>. This string must not contain a path separator character.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_UNRECOGNIZED_PATH</code></dt> + <dd> + Indicates that aNode incorrectly contains a path separator character.</dd> +</dl> +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="appendNative">appendNative</h3></div><p></p> +<p>This method is used for constructing a descendant of the current <code>nsIFile</code>. [native character encoding variant]</p> +<pre class="eval">void appendNative( + in ACString node +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>node</code></dt> + <dd> + A string that is intended to be a child node of the current <code>nsIFile</code>. This string must not contain a path separator character. This string must be encoded using the native character encoding.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_UNRECOGNIZED_PATH</code></dt> + <dd> + Indicates that aNode incorrectly contains a path separator character.</dd> +</dl> +<h3 id="clone()" name="clone()">clone()</h3> +<p>This method creates a clone of the <code>nsIFile</code>. (It does NOT clone the file itself; see the copy methods.)</p> +<pre class="eval">nsIFile clone(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p>A new <code>nsIFile</code> instance that corresponds to the same file or directory as this <code>nsIFile</code>.</p> +<h3 id="contains()" name="contains()">contains()</h3> +<p>This method tests whether or not a <code>nsIFile</code> instance is a descendant of the this <code>nsIFile</code>.</p> +<pre class="eval">boolean contains( + in nsIFile inFile, + in boolean recur +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>inFile</code></dt> + <dd> + The <code>nsIFile</code> to test.</dd> + <dt> + <code>recur</code></dt> + <dd> + This parameter specifies whether or not subdirectories should be inspected. As of <span title="">Gecko 1.7</span>, this parameter is ignored and always treated as false by the canonical Local File implementation.</dd> +</dl> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if inFile is a descendant of this <code>nsIFile</code>.</p> +<h3 id="copyTo()" name="copyTo()">copyTo()</h3> +<p>This method copies a source file to a new location if it does not already exist.</p> +<p>This method will NOT resolve aliases/shortcuts during the copy.</p> +<pre class="eval">void copyTo( + in nsIFile newParentDir, + in AString newName +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>newParentDir</code></dt> + <dd> + This parameter specifies the parent directory to copy the file into. If this parameter is <code>null</code>, then the parent directory of the file will be used.</dd> + <dt> + <code>newName</code></dt> + <dd> + This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + If the "newParentDir" is not a directory.</dd> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_ALREADY_EXISTS</code></dt> + <dd> + Indicates that there is already a file named "newName" in the destination directory.</dd> +</dl> +<h3 id="copyToFollowingLinks()" name="copyToFollowingLinks()">copyToFollowingLinks()</h3> +<p>This method copies a source file to a new location if it does not already exist.</p> +<p>This method is identical to <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile#copyTo()">copyTo()</a></code> except that any symbolic links will be followed as the name suggests.</p> +<pre class="eval">void copyToFollowingLinks( + in nsIFile newParentDir, + in AString newName +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>newParentDir</code></dt> + <dd> + This parameter specifies the parent directory to copy the file into. If this parameter is <code>null</code>, then the parent directory of the file will be used.</dd> + <dt> + <code>newName</code></dt> + <dd> + This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + If the "newParentDir" is not a directory.</dd> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_ALREADY_EXISTS</code></dt> + <dd> + Indicates that there is already a file named "newName" in the destination directory.</dd> +</dl> +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="copyToFollowingLinksNative">copyToFollowingLinksNative</h3></div><p></p> +<p>This method copies this file to a new location. [native character encoding variant]</p> +<p>This method is identical to <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile#copyToNative()">copyToNative()</a></code> except that any symbolic links will be followed as the name suggests.</p> +<pre class="eval">void copyToFollowingLinksNative( + in nsIFile newParentDir, + in ACString newName +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>newParentDir</code></dt> + <dd> + This parameter specifies the parent directory to copy the file into. If this parameter is <code>null</code>, then the parent directory of the file will be used.</dd> + <dt> + <code>newName</code></dt> + <dd> + This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used. This string must be encoded using the native character encoding.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + If the "newParentDir" is not a directory.</dd> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_ALREADY_EXISTS</code></dt> + <dd> + Indicates that there is already a file named "newName" in the destination directory.</dd> +</dl> +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="CopyToNative">CopyToNative</h3></div><p></p> +<p>This method copies this file to a new location. [native character encoding variant]</p> +<pre class="eval">void CopyToNative( + in nsIFile newParentDir, + in ACString newName +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>newParentDir</code></dt> + <dd> + This parameter specifies the parent directory to copy the file into. If this parameter is <code>null</code>, then the parent directory of the file will be used.</dd> + <dt> + <code>newName</code></dt> + <dd> + This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used. This string must be encoded using the native character encoding.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + If the "newParentDir" is not a directory.</dd> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to copy a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_ALREADY_EXISTS</code></dt> + <dd> + Indicates that there is already a file named "newName" in the destination directory.</dd> +</dl> +<h3 id="create()" name="create()">create()</h3> +<p>This method creates a new file or directory in the file system corresponding to the file path represented by this <code>nsIFile</code>. This method will create any path segments that do not already exist.</p> +<pre class="eval">void create( + in unsigned long type, + in unsigned long permissions +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>type</code></dt> + <dd> + This specifies the type of file system object to be made. The only two types at this time are file and directory which are defined above.</dd> + <dt> + <code>permissions</code></dt> + <dd> + A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_ALREADY_EXISTS</code></dt> + <dd> + Indicates that the file or directory already exists.</dd> + <dt> + <code>NS_ERROR_FILE_UNKNOWN_TYPE</code></dt> + <dd> + Indicates that the value of "type" does not correspond to a known type.</dd> +</dl> +<h3 id="createUnique()" name="createUnique()">createUnique()</h3> +<p>This function will create a new file or directory in the file system. Any nodes that have not been created or resolved, will be. If this file already exists, we try variations on the leaf name "suggestedName" until we find one that did not already exist. This method will create any path segments that do not already exist.</p> +<pre class="eval">void createUnique( + in unsigned long type, + in unsigned long permissions +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>type</code></dt> + <dd> + This specifies the type of file system object to be made. The only two types at this time are file and directory which are defined above.</dd> + <dt> + <code>permissions</code></dt> + <dd> + A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_UNKNOWN_TYPE</code></dt> + <dd> + Indicates that the value of "type" does not correspond to a known type.</dd> + <dt> + <code>NS_ERROR_FILE_TOO_BIG</code></dt> + <dd> + Indicates that the search for nonexistent files was unsuccessful because all of the attempted leaf name variants already exist.</dd> +</dl> +<h3 id="equals()" name="equals()">equals()</h3> +<p>This method tests whether or not two <code>nsIFile</code> instances correspond to the same file or directory.</p> +<pre class="eval">boolean equals( + in nsIFile inFile +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>inFile</code></dt> + <dd> + The <code>nsIFile</code> to compare this <code>nsIFile</code> against.</dd> +</dl> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if "inFile" is equivalent to this <code>nsIFile</code>.</p> +<h3 id="exists()" name="exists()">exists()</h3> +<p>This method tests whether or not this <code>nsIFile</code> exists.</p> +<pre class="eval">boolean exists() +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if the file or directory exists. Otherwise it returns <code>false</code>.</p> +<h3 id="isDirectory()" name="isDirectory()">isDirectory()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a directory.</p> +<pre class="eval">boolean isDirectory(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if this <code>nsIFile</code> corresponds to a directory. Otherwise it returns <code>false</code>.</p> +<h3 id="isExecutable()" name="isExecutable()">isExecutable()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a file that may be executed.</p> +<div class="note style-wrap"> + <p><strong>Note:</strong> This method does not work on all platforms due to <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=322865" title="isExecutable method of nsILocalFile reports false for executable files on OSX">bug 322865</a>.</p> +</div> +<pre class="eval">boolean isExecutable(); +</pre> +<div class="note style-wrap"> + <p><strong>Note:</strong> Use <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIProcess" title="">nsIProcess</a></code> to then execute/run this file.</p> +</div> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if the <code>nsIFile</code> may be executed by the user. Otherwise it returns <code>false</code>.</p> +<h3 id="isFile()" name="isFile()">isFile()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a normal file.</p> +<pre class="eval">boolean isFile(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if this <code>nsIFile</code> corresponds to a normal file. Otherwise it returns <code>false</code>.</p> +<h3 id="isHidden()" name="isHidden()">isHidden()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a file or directory that is hidden. In Unix, hidden files start with a period. On Mac and Windows, they have an attribute bit set.</p> +<pre class="eval">boolean isHidden(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if the file or directory is hidden. Otherwise it returns <code>false</code>.</p> +<h3 id="isReadable()" name="isReadable()">isReadable()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a file or directory that may be read by the user.</p> +<pre class="eval">boolean isReadable(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if the file or directory may be read by the user. Otherwise it returns <code>false</code>.</p> +<h3 id="isSpecial()" name="isSpecial()">isSpecial()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a special system file.</p> +<p></p><div class="blockIndicator note"><strong>Note:</strong> The definition of a special system file is platform dependent. For example, under UNIX platforms this might correspond to a device file, socket, or fifo.</div><p></p> +<pre class="eval">boolean isSpecial(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if this <code>nsIFile</code> corresponds to a special system file. Otherwise it returns <code>false</code>.</p> +<h3 id="isSymlink()" name="isSymlink()">isSymlink()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a symbolic link, shortcut, or alias.</p> +<pre class="eval">boolean isSymlink(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if this <code>nsIFile</code> corresponds to a symbolic link. Otherwise it returns <code>false</code>.</p> +<h3 id="isWritable()" name="isWritable()">isWritable()</h3> +<p>This method tests whether or not this <code>nsIFile</code> corresponds to a file or directory that may be modified by the user. As of Gecko 9, files on read only shares will return false. Files that are exclusively opened on Win32 will return true if they are normally writable, and files that don't have write permissions will return false. For specific handling before Gecko 9 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6), please see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=682571" title="FIXED: nsLocalFile::isWritable behaves wrongly on Windows">bug 682571</a>.</p> +<pre class="eval">boolean isWritable(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Return_value" name="Return_value">Return value</h6> +<p><code>true</code> if the file or directory may be modified by the user. Otherwise it returns <code>false</code>.</p> +<h3 id="moveTo()" name="moveTo()">moveTo()</h3> +<p>This method moves this file to a new location.</p> +<div class="note"> + <strong>Note:</strong> If this method succeeds, this instance will be updated to point to the new file.</div> +<p>If the current file path corresponds to a regular file (for storage of bytes), and if the new leaf name identifies a regular file that already exists, then this method will overwrite the destination file.</p> +<p>Usually, "move" means to relocate the file to a different directory without changing the file's contents or properties, or in fact the file's serial number (inode). That is a very fast operation because it just changes directory information. The actual data doesn't move.</p> +<p>Unfortunately, an actual "move" is impossible between different volumes (disks or partitions). This method attempts to do the "right thing" when moving files across volumes. That is, it will copy the old file to the new location, try to assign the file attributes as the old file had them, and then delete the old file. You should be aware of these possible problems:</p> +<ul> + <li>This process may take a long time if the file is large and/or the bandwidth is narrow.</li> + <li>If the <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile#copyTo()">copyTo()</a></code> method loses data, such as Mac resource data, then so will such a move.</li> + <li>If attribute data cannot be recreated (like the file owner if you don't have enough privileges, or ACL data if moving to a non-ACL volume), then those attributes will be lost.</li> + <li>The new file's serial number will almost certainly be different, because it is a different file, probably stored in a different physical location.</li> +</ul> +<pre class="eval">void moveTo( + in nsIFile newParentDir, + in AString newName +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>newParentDir</code></dt> + <dd> + This parameter specifies the parent directory to move the file into. If this parameter is <code>null</code>, then the parent directory of the file will be used.</dd> + <dt> + <code>newName</code></dt> + <dd> + This parameter allows you to specify a new leaf name for the file to be moved. This parameter may be empty, in which case the current leaf name will be used.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to move a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_DIR_NOT_EMPTY</code></dt> + <dd> + Indicates that an attempt was made to move a directory to the location of an existing directory that is not empty.</dd> + <dt> + <code>NS_ERROR_FILE_ACCESS_DENIED</code></dt> + <dd> + Indicates that an attempt was made to move a directory to the location of an existing directory that is not writable.</dd> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + Indicates that "newParentDir" exists and is not a directory.</dd> +</dl> +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="moveToNative">moveToNative</h3></div><p></p> +<p>This method moves this file to a new location. [native character encoding variant]</p> +<div class="note"> + <strong>Note:</strong> If this method succeeds, this instance will be updated to point to the new file.</div> +<p>If the current file path corresponds to a regular file (for storage of bytes), and if the new leaf name identifies a regular file that already exists, then this method will overwrite the destination file.</p> +<p>Usually, "move" means to relocate the file to a different directory without changing the file's contents or properties, or in fact the file's serial number (inode). That is a very fast operation because it just changes directory information. The actual data doesn't move.</p> +<p>Unfortunately, an actual "move" is impossible between different volumes (disks or partitions). This method attempts to do the "right thing" when moving files across volumes. That is, it will copy the old file to the new location, try to assign the file attributes as the old file had them, and then delete the old file. You should be aware of these possible problems:</p> +<ul> + <li>This process may take a long time if the file is large and/or the bandwidth is narrow.</li> + <li>If the <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile#copyTo()">copyTo()</a></code> method loses data, such as Mac resource data, then so will such a move.</li> + <li>If attribute data cannot be recreated (like the file owner if you don't have enough privileges, or ACL data if moving to a non-ACL volume), then those attributes will be lost.</li> + <li>The new file's serial number will almost certainly be different, because it is a different file, probably stored in a different physical location.</li> +</ul> +<pre class="eval">void moveToNative( + in nsIFile newParentDir, + in ACString newName +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p> </p> +<dl> + <dt> + <code>newParentDir</code></dt> + <dd> + This parameter specifies the parent directory to copy the file into. If this parameter is <code>null</code>, then the parent directory of the file will be used.</dd> + <dt> + <code>newName</code></dt> + <dd> + This parameter allows you to specify a new leaf name for the file to be copied. This parameter may be empty, in which case the current leaf name will be used. This string must be encoded using the native character encoding.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to move a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_DIR_NOT_EMPTY</code></dt> + <dd> + Indicates that an attempt was made to move a directory to the location of an existing directory that is not empty.</dd> + <dt> + <code>NS_ERROR_FILE_ACCESS_DENIED</code></dt> + <dd> + Indicates that an attempt was made to move a directory to the location of an existing directory that is not writable.</dd> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + Indicates that "newParentDir" exists and is not a directory.</dd> +</dl> +<h3 id="normalize()" name="normalize()">normalize()</h3> +<p>This method is used to canonicalize the path represented by this <code>nsIFile</code>. (for example removing .. and . components on Unix).</p> +<p>As of <span title="">Gecko 1.7</span>, this method is only implemented under UNIX builds (except for Mac OSX). This method will fail if the path does not exist.</p> +<pre class="eval">void normalize(); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<p>None.</p> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the file path does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_DESTINATION_NOT_DIR</code></dt> + <dd> + Indicates that a component of the path prefix is not a directory.</dd> + <dt> + <code>NS_ERROR_FILE_ACCESS_DENIED</code></dt> + <dd> + Read or search permission was denied for a component of the path prefix.</dd> +</dl> +<h3 id="remove()" name="remove()">remove()</h3> +<p>This method removes the file or directory corresponding to the file path represented by this <code>nsIFile</code>.</p> +<p>This method will not resolve any symlinks.</p> +<pre class="eval">void remove( + in boolean recursive +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>recursive</code></dt> + <dd> + If this <code>nsIFile</code> corresponds to a directory that is not empty, then this parameter must be <code>true</code> in order for the directory to be deleted. Otherwise, this parameter is ignored.</dd> +</dl> +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> +<dl> + <dt> + <code>NS_ERROR_FILE_TARGET_DOES_NOT_EXIST</code></dt> + <dd> + Indicates that the current file path does not exist. It is not possible to remove a file that does not exist.</dd> + <dt> + <code>NS_ERROR_FILE_DIR_NOT_EMPTY</code></dt> + <dd> + Indicates that an attempt was made to remove a directory that is not empty.</dd> + <dt> + <code>NS_ERROR_FILE_ACCESS_DENIED</code></dt> + <dd> + Indicates that an attempt was made to remove a file in a way that exceeded your permissions. Details depend on your file system and how its permissions work.</dd> +</dl> +<h2 id="Remarks" name="Remarks">Remarks</h2> +<p>All string-valued methods and attributes have two forms. The preferred form operates on UTF-16 (Unicode) encoded character strings. The alternate form operates on character strings encoded in the "native" multibyte character set. The native character encoding is defined as the single-byte character encoding used with the standard fopen function on the host system.</p> +<p>The native character encoding is determined using platform specific methods. As of <span title="">Gecko 1.7</span>, it is UTF-8 on Mac OS X. On Linux and other UNIX platforms, it is the value returned from nl_langinfo (CODESET), which usually corresponds to the value of the LC_ALL, LC_CTYPE and LANG environment variables (with the precedence the same as the order they're enumerated). On Win32 platforms, it is the currently selected ANSI codepage (specified by CP_ACP).</p> +<p>The word "Native" appears in the name of methods that operate on or return strings encoded in the native character set.</p> +<p>A string containing characters encoded in the native character set cannot be safely passed to JavaScript via XPConnect. Therefore, the "native" methods and attributes are not scriptable.</p> +<p>XPCOM provides the string conversion functions <a href="/en/NS_CStringToUTF16" title="en/NS_CStringToUTF16">NS_CStringToUTF16</a> and <a href="/en/NS_UTF16ToCString" title="en/NS_UTF16ToCString">NS_UTF16ToCString</a>, which can be used to convert a string between UTF-16 and the native character encoding.</p> +<p>This interface was frozen for <span title="">Gecko 1.0</span>. See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=129279" title="FIXED: nsIFile unicode/utf8/ascii task">bug 129279</a> for details. From <span title="(Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)">Gecko 2.0</span> interfaces are no longer frozen.</p> +<h2 id="See_also" name="See_also">See also</h2> +<ul> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile" title="">nsILocalFile</a></code></li> + <li><a href="/en/NS_CStringToUTF16" title="en/NS_CStringToUTF16">NS_CStringToUTF16</a></li> + <li><a href="/en/NS_UTF16ToCString" title="en/NS_UTF16ToCString">NS_UTF16ToCString</a></li> +</ul> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsifilepicker/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsifilepicker/index.html new file mode 100644 index 0000000000..7122dcd1ef --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsifilepicker/index.html @@ -0,0 +1,376 @@ +--- +title: nsIFilePicker +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker +tags: + - Filepicker + - 文件选取器 +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/widget/nsIFilePicker.idl" rel="custom">widget/nsIFilePicker.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +文件选择器组件是通过显示标准的用户界面来让用户来选择文件和目录，以及选择目的地来命名和新建文件。 +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 17.0 (Firefox 17.0 / Thunderbird 17.0 / SeaMonkey 2.14)</span></div> +</div><p></p> + +<p>实现自： <code>@mozilla.org/filepicker;1</code>。要创建一个实例，使用以下代码：</p> + +<pre class="eval">var filePicker = Components.classes["@mozilla.org/filepicker;1"] + .createInstance(Components.interfaces.nsIFilePicker); +</pre> + +<h2 id="Method_overview" name="Method_overview">方法概述</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#appendFilter()">appendFilter</a>(in AString title, in AString filter);</code></td> + </tr> + <tr> + <td><code>void <a href="#appendFilters()">appendFilters</a>(in long filterMask);</code></td> + </tr> + <tr> + <td><code>void <a href="#init()">init</a>(in nsIDOMWindow parent, in AString title, in short mode);</code></td> + </tr> + <tr> + <td><code>void <a href="#open()">open</a>(in nsIFilePickerShownCallback aFilePickerShownCallback);</code> </td> + </tr> + <tr> + <td><code>short <a href="#show()">show</a>();</code> <span class="inlineIndicator deprecated deprecatedInline" title="(Firefox 17.0 / Thunderbird 17.0 / SeaMonkey 2.14)">已废弃 Gecko 17.0</span></td> + </tr> + </tbody> +</table> + +<h2 id="Attributes" name="Attributes">属性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">属性</td> + <td class="header">类型</td> + <td class="header">说明</td> + </tr> + <tr> + <td><code>addToRecentDocs</code> </td> + <td><code>boolean</code></td> + <td>If <code>true</code>, the file is added to the operating system's "recent documents" list (if the operating system has one; nothing happens if there is no such concept on the user's platform). This attribute has no effect if private browsing mode is in effect.</td> + </tr> + <tr> + <td><code>defaultExtension</code></td> + <td><code><a href="/en/AString" title="en/AString">AString</a></code></td> + <td>The extension for the type of files you want to work with. On some platforms, this is automatically appended to filenames the user enters, if required. Specify it without a leading dot, for example "jpg".</td> + </tr> + <tr> + <td><code>defaultString</code></td> + <td><code><a href="/en/AString" title="en/AString">AString</a></code></td> + <td>The filename, including extension, that should be suggested to the user as a default. This should be set this before calling <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker#open()">open()</a></code> or <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker#show()">show()</a></code>. + <h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If you try to read this attribute.</dd> + </dl> + </td> + </tr> + <tr> + <td><code>displayDirectory</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile" title="">nsILocalFile</a></code></code></td> + <td>The directory that the file picker dialog should initially display. This should be set this before calling <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker#open()">open()</a></code> or <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker#show()">show()</a></code> to specify a starting point.</td> + </tr> + <tr> + <td><code>file</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile" title="">nsILocalFile</a></code></code></td> + <td>The currently selected file or directory. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>files</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISimpleEnumerator" title="">nsISimpleEnumerator</a></code></code></td> + <td> + <p>An enumerator of the currently selected files. <strong>Read only.</strong></p> + <div class="blockIndicator note"><strong>Note:</strong> Only works with <code>modeOpenMultiple</code> mode.</div></td> + </tr> + <tr> + <td><code>fileURL</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIURI" title="">nsIURI</a></code></code></td> + <td>The URI of the currently selected file or directory. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>filterIndex</code></td> + <td><code><a href="/en/long" title="en/long">long</a></code></td> + <td>The (0-based) index of the filter which is currently selected in the file picker dialog. Set this to choose a particular filter to be selected by default.</td> + </tr> + </tbody> +</table> + +<h2 id="Constants" name="Constants">常量</h2> + +<h3 id="Mode_constants" name="Mode_constants">模式常量</h3> + +<p>These constants are used to specify the type of file picker to create when calling <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker#init()">init()</a></code>.</p> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">常量</td> + <td class="header">值</td> + <td class="header">说明</td> + </tr> + <tr> + <td><code>modeOpen</code></td> + <td><code>0</code></td> + <td>Load a file or directory.</td> + </tr> + <tr> + <td><code>modeSave</code></td> + <td><code>1</code></td> + <td>Save a file or directory.</td> + </tr> + <tr> + <td><code>modeGetFolder</code></td> + <td><code>2</code></td> + <td>Select a folder/directory.</td> + </tr> + <tr> + <td><code>modeOpenMultiple</code></td> + <td><code>3</code></td> + <td>Load multiple files.</td> + </tr> + </tbody> +</table> + +<h3 id="Return_value_constants" name="Return_value_constants">返回值常量</h3> + +<p>These values are returned by <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePicker#show()">show()</a></code>, indicating the result of the file picker activity.</p> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>returnOK</code></td> + <td><code>0</code></td> + <td>The file picker dialog was closed by the user hitting 'Ok'</td> + </tr> + <tr> + <td><code>returnCancel</code></td> + <td><code>1</code></td> + <td>The file picker dialog was closed by the user hitting 'Cancel'</td> + </tr> + <tr> + <td><code>returnReplace</code></td> + <td><code>2</code></td> + <td>The user chose an existing file and acknowledged that they want to overwrite the file</td> + </tr> + </tbody> +</table> + +<h3 id="Filter_constants" name="Filter_constants">筛选器常量</h3> + +<p>These constants are used to create filters for commonly-used file types. For the most up to date list see <a href="https://dxr.mozilla.org/mozilla-central/source/toolkit/content/filepicker.properties" rel="custom">filepicker.properties</a>.</p> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>filterAll</code></td> + <td><code>0x001</code></td> + <td>Corresponds to the *.* filter for file extensions. All files will pass through the filter.</td> + </tr> + <tr> + <td><code>filterHTML</code></td> + <td><code>0x002</code></td> + <td>Corresponds to the *.html, *.htm, *.shtml and *.xhtml filters for file extensions.</td> + </tr> + <tr> + <td><code>filterText</code></td> + <td><code>0x004</code></td> + <td>Corresponds to the *.txt and *.text filter for file extensions.</td> + </tr> + <tr> + <td><code>filterImages</code></td> + <td><code>0x008</code></td> + <td>Corresponds to the *.jpe, *.jpg, *.jpeg, *.gif, *.png, *.bmp, *.ico, *.svg, *.svgz, *.tif, *.tiff, *.ai, *.drw, *.pct, *.psp, *.xcf, *.psd and *.raw filters for file extensions.</td> + </tr> + <tr> + <td><code>filterXML</code></td> + <td><code>0x010</code></td> + <td>Corresponds to the *.xml filter for file extensions.</td> + </tr> + <tr> + <td><code>filterXUL</code></td> + <td><code>0x020</code></td> + <td>Corresponds to the *.xul filter for file extensions.</td> + </tr> + <tr> + <td><code>filterApps</code></td> + <td><code>0x040</code></td> + <td>Corresponds to the platform specific application filter for file extensions. Application files for the user's platform will pass through the filter.</td> + </tr> + <tr> + <td><code>filterAllowURLs</code></td> + <td><code>0x80</code></td> + <td>Allow URLs. </td> + </tr> + <tr> + <td><code>filterAudio</code></td> + <td><code>0x100</code></td> + <td>Corresponds to the *.aac, *.aif, *.flac, *.iff, *.m4a, *.m4b, *.mid, *.midi, *.mp3, *.mpa, *.mpc, *.oga, *.ogg, *.ra, *.ram, *.snd, *.wav and *.wma filters for file extensions. </td> + </tr> + <tr> + <td><code>filterVideo</code></td> + <td><code>0x200</code></td> + <td>Corresponds to the *.avi, *.divx, *.flv, *.m4v, *.mkv, *.mov, *.mp4, *.mpeg, *.mpg, *.ogm, *.ogv, *.ogx, *.rm, *.rmvb, *.smil, *.webm, *.wmv and *.xvid filters for file extensions. </td> + </tr> + </tbody> +</table> + +<h2 id="Methods" name="Methods">方法</h2> + +<h3 id="appendFilter()" name="appendFilter()">appendFilter()</h3> + +<p>Appends a custom file extension filter to the dialog. The filter appended first will be used to display the <code>nsIFilePicker</code> dialog, the user may then select another from the list.</p> + +<pre class="eval">void appendFilter( + in AString title, + in AString filter +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>title</code></dt> + <dd>The title of the filter.</dd> + <dt><code>filter</code></dt> + <dd>The filter string. Multiple extensions may be included, separated by a semicolon and a space.</dd> +</dl> + +<h6 id="appendFilter_example" name="appendFilter_example">Example</h6> + +<p>Some example filter strings:</p> + +<ul> + <li>"*.ics"</li> + <li>"*.txt; *.doc; *.rtf"</li> +</ul> + +<h3 id="appendFilters()" name="appendFilters()">appendFilters()</h3> + +<p>Appends a list of file extension filters, from the predefined list, to the dialog.</p> + +<pre class="eval">void appendFilters( + in long filterMask +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<div class="note"><strong>Note:</strong> If <code>appendFilters</code> is the first (or only) call to set the file filters the filter with the smallest code will be used as default filter when displaying the <code>nsIFilePicker</code> dialog. If you would like to use another you must append it separately before the others you want to go into the drop down list.</div> + +<dl> + <dt><code>filterMask</code></dt> + <dd>A combination of the <a class="internal" href="#Filter_constants" title="Filter constants">filters</a> you wish to use. You may OR multiple filters together; for example <code>filterAll | filterHTML</code>.</dd> +</dl> + +<h3 id="init()" name="init()">init()</h3> + +<p>Initialize the file picker widget. The file picker is not valid until this method is called.</p> + +<pre class="eval">void init( + in nsIDOMWindow parent, + in AString title, + in short mode +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>parent</code></dt> + <dd>The <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> parent. This dialog will be dependent on this parent. Must be non-null.</dd> + <dt><code>title</code></dt> + <dd>The file picker dialog title. If this is <code>null</code>, the dialog will have the default title.</dd> + <dt><code>mode</code></dt> + <dd>One of the <a class="internal" href="#Mode_constants" title="Mode constants">mode constants</a>, indicating the type of picker to create.</dd> +</dl> + +<h3 id="open">open</h3> + +<p>Opens the file dialog asynchrounously. The passed in object's done method will be called upon completion.</p> + +<pre class="eval">void open( + in nsIFilePickerShownCallback aFilePickerShownCallback +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>aFilePickerShownCallback</code></dt> + <dd>The <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFilePickerShownCallback" title="">nsIFilePickerShownCallback</a></code> to be called on completion.</dd> +</dl> + +<h3 id="show">show</h3> + +<p>Displays the file picker dialog. The dialog is displayed modally.</p> + +<pre class="eval">short show(); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<p>None.</p> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>One of the <a class="internal" href="#Return_value_constants" title="Return value constants">return constants</a>.</p> + +<h2 id="Example" name="Example">示例</h2> + +<p>Here's an example:</p> + +<pre>const nsIFilePicker = Components.interfaces.nsIFilePicker; + +var fp = Components.classes["@mozilla.org/filepicker;1"] + .createInstance(nsIFilePicker); +fp.init(window, "Dialog Title", nsIFilePicker.modeOpen); +fp.appendFilters(nsIFilePicker.filterAll | nsIFilePicker.filterText); + +var rv = fp.show(); +if (rv == nsIFilePicker.returnOK || rv == nsIFilePicker.returnReplace) { + var file = fp.file; + // Get the path as string. Note that you usually won't + // need to work with the string paths. + var path = fp.file.path; + // work with returned nsILocalFile... +} +</pre> + +<p>If your code is a component and <code>window</code> is not defined, you can get one using <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIWindowMediator" title="">nsIWindowMediator</a></code>.</p> + +<p>When selecting multiple files:</p> + +<pre> .... + fp.init(window, "Dialog Title", nsIFilePicker.modeOpenMultiple); + .... + + var files = fp.files; + var paths = []; + while (files.hasMoreElements()) + { + var arg = files.getNext().QueryInterface(Components.interfaces.nsILocalFile).path; + paths.push(arg); + } +</pre> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsihttpchannel/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsihttpchannel/index.html new file mode 100644 index 0000000000..b469773f43 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsihttpchannel/index.html @@ -0,0 +1,365 @@ +--- +title: nsIHttpChannel +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIHttpChannel +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIHttpChannel +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/netwerk/protocol/http/nsIHttpChannel.idl" rel="custom">netwerk/protocol/http/nsIHttpChannel.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +This interface allows for the modification of HTTP request parameters and the inspection of the resulting HTTP response status and headers when they become available. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIChannel" title="">nsIChannel</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.3 </span></div> +</div><p></p> + +<p>To create an HTTP channel, use <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIIOService" title="">nsIIOService</a></code> with a HTTP URI, for example:</p> + +<pre class="eval">var ios = Components.classes["@mozilla.org/network/io-service;1"] + .getService(Components.interfaces.nsIIOService); +var ch = ios.newChannel("<a class="linkification-ext external" href="http://www.example.com/" title="Linkification: http://www.example.com/">http://www.example.com/</a>", null, null); +</pre> + +<h2 id="Method_overview" name="Method_overview">方法概述</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>ACString <a href="#getRequestHeader()">getRequestHeader</a>(in ACString aHeader);</code></td> + </tr> + <tr> + <td><code>ACString <a href="#getResponseHeader()">getResponseHeader</a>(in ACString header);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isNoCacheResponse()">isNoCacheResponse</a>();</code></td> + </tr> + <tr> + <td><code>boolean <a href="#isNoStoreResponse()">isNoStoreResponse</a>();</code></td> + </tr> + <tr> + <td><code>void <a href="#setRequestHeader()">setRequestHeader</a>(in ACString aHeader, in ACString aValue, in boolean aMerge);</code></td> + </tr> + <tr> + <td><code>void <a href="#setResponseHeader()">setResponseHeader</a>(in ACString header, in ACString value, in boolean merge);</code></td> + </tr> + <tr> + <td><code>void <a href="#visitRequestHeaders()">visitRequestHeaders</a>(in nsIHttpHeaderVisitor aVisitor);</code></td> + </tr> + <tr> + <td><code>void <a href="#visitResponseHeaders()">visitResponseHeaders</a>(in nsIHttpHeaderVisitor aVisitor);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Attributes" name="Attributes">属性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">属性名</td> + <td class="header">类型</td> + <td class="header">描述</td> + </tr> + <tr> + <td><code>allowPipelining</code></td> + <td><code><a href="/zh-CN/boolean" title="zh-CN/boolean">boolean</a></code></td> + <td> + <p>This attribute is a hint to the channel to indicate whether or not the underlying HTTP transaction should be allowed to be pipelined with other transactions. This should be set to <code>false</code>, for example, if the application knows that the corresponding document is likely to be very large.</p> + + <p>This attribute is <code>true</code> by default, though other factors may prevent pipelining.</p> + This attribute may only be set before the channel is opened. + + <h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If set after the channel has been opened.</dd> + </dl> + </td> + </tr> + <tr> + <td><code>redirectionLimit</code></td> + <td><code><a href="/zh-CN/unsigned_long" title="zh-CN/unsigned long">unsigned long</a></code></td> + <td> + <p>This attribute specifies the number of redirects this channel is allowed to make. If zero, the channel will fail to redirect and will generate a <code>NS_ERROR_REDIRECT_LOOP</code> failure status.</p> + <div class="blockIndicator note"><strong>Note:</strong> An HTTP redirect results in a new channel being created. If the new channel supports <code>nsIHttpChannel</code>, then it will be assigned a value to its <code>redirectionLimit</code> attribute one less than the value of the redirected channel's <code>redirectionLimit</code> attribute. The initial value for this attribute may be a configurable preference (depending on the implementation).</div></td> + </tr> + <tr> + <td><code>referrer</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIURI" title="">nsIURI</a></code></code></td> + <td> + <p>Get or set the URI of the HTTP <code>Referer:</code> header. This is the address (URI) of the resource from which this channel's URI was obtained (see RFC2616 section 14.36).</p> + + <p>This attribute may only be set before the channel is opened.</p> + <div class="blockIndicator note"><strong>Note:</strong> The channel may silently refuse to set the Referer: header if the URI does not pass certain security checks (e.g., a "https://" URL will never be sent as the <code>referrer</code> for a plaintext HTTP request). The implementation is not required to throw an exception when the <code>referrer</code> URI is rejected.</div> + + <h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + + <dl> + <dt><code>NS_ERROR_IN_PROGRESS</code></dt> + <dd>If set after the channel has been opened.</dd> + </dl> + </td> + </tr> + <tr> + <td><code>requestMethod</code></td> + <td><code><a href="/zh-CN/ACString" title="zh-CN/ACString">ACString</a></code></td> + <td> + <p>获取或设置HTTP请求方法(默认为"GET").设置时不区分大小写,获取时返回的都是大写字母组成的字符串.</p> + + <p>该属性的值只能在通道打开之前进行设置.</p> + + <p></p><div class="blockIndicator note"><strong>Note:</strong> The data for a "POST" or "PUT" request can be configured via <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIUploadChannel" title="">nsIUploadChannel</a></code>. However, after setting the upload data, it may be necessary to set the request method explicitly. The documentation for <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIUploadChannel" title="">nsIUploadChannel</a></code> has further details. </div><p></p> + + <h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + + <dl> + <dt><code>NS_ERROR_IN_PROGRESS</code></dt> + <dd>If set after the channel has been opened.</dd> + </dl> + </td> + </tr> + <tr> + <td><code>requestSucceeded</code></td> + <td><code><a href="/zh-CN/boolean" title="zh-CN/boolean">boolean</a></code></td> + <td> + <p>Returns <code>true</code> if the HTTP response code indicates success. The value of <code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIRequest#status()">nsIRequest.status()</a></code> will be NS_OK even when processing a <code><a href="/zh-CN/HTTP/HTTP_response_codes#404" title="https://developer.mozilla.org/zh-CN/HTTP/HTTP_response_codes#404">404 File Not Found</a></code> response because such a response may include a message body that (in some cases) should be shown to the user. Use this attribute to distinguish server error pages from normal pages, instead of comparing the response status manually against the set of valid response codes, if that is required by your application. <strong>Read only.</strong></p> + + <h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + + <dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>If called before the response has been received (before <code>onStartRequest()</code>).</dd> + </dl> + </td> + </tr> + <tr> + <td><code>responseStatus</code></td> + <td><code><a href="/zh-CN/unsigned_long" title="zh-CN/unsigned long">unsigned long</a></code></td> + <td>获取HTTP响应状态码(比如200). <strong>只读.</strong> + <h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + + <dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>If called before the response has been received (before <code>onStartRequest()</code>).</dd> + </dl> + </td> + </tr> + <tr> + <td><code>responseStatusText</code></td> + <td><code><a href="/zh-CN/ACString" title="zh-CN/ACString">ACString</a></code></td> + <td> + <p>获取HTTP响应状态信息(比如"OK").</p> + <div class="blockIndicator note"><strong>Note:</strong> This returns the raw (possibly 8-bit) text from the server. There are no assumptions made about the charset of the returned text. You have been warned!</div> <strong>Read only.</strong> + + <h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + + <dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>If called before the response has been received (before <code>onStartRequest()</code>).</dd> + </dl> + </td> + </tr> + </tbody> +</table> + +<h2 id="Methods" name="Methods">方法</h2> + +<h3 id="getRequestHeader()" name="getRequestHeader()">getRequestHeader()</h3> + +<p>Get the value of a particular request header.</p> + +<pre class="eval">ACString getRequestHeader( + in ACString aHeader +); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<dl> + <dt><code>aHeader</code></dt> + <dd>需要查询的请求头名称,不区分大小写(比如"Cache-Control").</dd> +</dl> + +<h6 id="Return_value" name="Return_value">返回值</h6> + +<p>指定请求头的值.</p> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>如果没有这个请求头</dd> +</dl> + +<h3 id="getResponseHeader()" name="getResponseHeader()">getResponseHeader()</h3> + +<p>获取指定响应头的值.</p> + +<pre class="eval">ACString getResponseHeader( + in ACString header +); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<dl> + <dt><code>header</code></dt> + <dd>需要查询的响应头名称,不区分大小写(比如"Set-Cookie").</dd> +</dl> + +<h6 id="Return_value" name="Return_value">返回值</h6> + +<p>指定响应头的值.</p> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>在响应头还未完全返回的时候调用了该方法(before <code>onStartRequest()</code>),或者响应中没有包含此响应头的情况下.</dd> +</dl> + +<h3 id="isNoCacheResponse()" name="isNoCacheResponse()">isNoCacheResponse()</h3> + +<p>Returns <code>true</code> if the server sent the equivalent of a "Cache-Control: no-cache" response header. Equivalent response headers include: "Pragma: no-cache", "Expires: 0", and "Expires" with a date value in the past relative to the value of the "Date" header.</p> + +<pre class="eval">boolean isNoCacheResponse(); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<p>无</p> + +<h6 id="Return_value" name="Return_value">返回值</h6> + +<p>如果服务器返回了"Cache-control: no-cache"或者其他能够禁止缓存的响应头,则<code>该方法返回true</code>,否则返回<code>false</code>.</p> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>在响应头还未完全返回的时候调用了该方法(before <code>onStartRequest()</code>).</dd> +</dl> + +<h3 id="isNoStoreResponse()" name="isNoStoreResponse()">isNoStoreResponse()</h3> + +<pre class="eval">boolean isNoStoreResponse(); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<p>无</p> + +<h6 id="Return_value" name="Return_value">返回值</h6> + +<p>如果服务器返回了"Cache-Control: no-store"这样的响应头,则<code>该方法返回true</code>,否则返回<code>false</code>.</p> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>在响应头还未完全返回的时候调用了该方法(before <code>onStartRequest()</code>).</dd> +</dl> + +<h3 id="setRequestHeader()" name="setRequestHeader()">setRequestHeader()</h3> + +<p>This method is called to set the value of a particular request header. This method allows, for example, the cookies module to add "Cookie" headers to the outgoing HTTP request. This method may only be called before the channel is opened. If aValue is empty and aMerge is <code>false</code>, the header will be cleared.</p> + +<pre class="eval">void setRequestHeader( + in ACString aHeader, + in ACString aValue, + in boolean aMerge +); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<dl> + <dt><code>aHeader</code></dt> + <dd>指定请求头的名称,不区分大小写(例如"Cookie").</dd> + <dt><code>aValue</code></dt> + <dd>指定请求头的值(例如"X=1").</dd> + <dt><code>aMerge</code></dt> + <dd>如果该参数为<code>true</code>,则新指定的请求头的值会合并到该请求头已有的值的后面.如果指定的请求头不支持(或者说不适合)新旧值的合并操作,则这个参数会被忽略(比如"<span>Connection</span>"头就只能有一个值).具体那些请求头会忽略掉这个参数,本文档不会给出.如果该参数的值为<code>false</code>,则新指定的请求头的值会覆盖掉该请求头已有的值.</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_IN_PROGRESS</code></dt> + <dd>在通道已经打开之后才调用了该方法</dd> +</dl> + +<h3 id="setResponseHeader()" name="setResponseHeader()">setResponseHeader()</h3> + +<p>设置指定响应头的值.This method allows, for example, the HTML content sink to inform the HTTP channel about HTTP-EQUIV headers found in HTML <META> tags. If value is empty and merge is <code>false</code>, the header will be cleared.</p> + +<pre class="eval">void setResponseHeader( + in ACString header, + in ACString value, + in boolean merge +); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<dl> + <dt><code>header</code></dt> + <dd>指定响应头的名称,不区分大小写(例如"Cache-Control").</dd> + <dt><code>value</code></dt> + <dd>指定响应头的值(例如"no-cache").</dd> + <dt><code>merge</code></dt> + <dd>如果该参数为<code>true</code>,则新指定的响应头的值会合并到该响应头已有的值的后面.如果指定的响应头不支持(或者说不适合)新旧值的合并操作,则这个参数会被忽略(比如"Content-Type"头就只能有一个值).具体那些响应头会忽略掉这个参数,本文档不会给出.如果该参数的值为<code>false</code>,则新指定的响应头的值会覆盖掉该响应头已有的值.</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>在响应头还未完全返回的时候调用了该方法(before <code>onStartRequest()</code>).</dd> + <dt><code>NS_ERROR_ILLEGAL_VALUE</code></dt> + <dd>If changing the value of this response header is not allowed.</dd> +</dl> + +<h3 id="visitRequestHeaders()" name="visitRequestHeaders()">visitRequestHeaders()</h3> + +<p>Call this method to visit all request headers. Calling <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIHttpChannel#setRequestHeader()">setRequestHeader()</a></code> while visiting request headers has undefined behavior. Don't do it!</p> + +<pre class="eval">void visitRequestHeaders( + in nsIHttpHeaderVisitor aVisitor +); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<dl> + <dt><code>aVisitor</code></dt> + <dd>The header visitor instance.</dd> +</dl> + +<h3 id="visitResponseHeaders()" name="visitResponseHeaders()">visitResponseHeaders()</h3> + +<p>Call this method to visit all response headers.</p> + +<p>{</p><div class="warning"> Calling <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIHttpChannel#setResponseHeader()">setResponseHeader()</a></code> while visiting response headers has undefined behavior. Don't do it! </div><p></p> + +<pre class="eval">void visitResponseHeaders( + in nsIHttpHeaderVisitor aVisitor +); +</pre> + +<h6 id="Parameters" name="Parameters">参数</h6> + +<dl> + <dt><code>aVisitor</code></dt> + <dd>The header visitor instance.</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">可能抛出的异常</h6> + +<dl> + <dt><code>NS_ERROR_NOT_AVAILABLE</code></dt> + <dd>If called before the response has been received (before <code>onStartRequest()</code>).</dd> +</dl> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiidleservice/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiidleservice/index.html new file mode 100644 index 0000000000..a0dec4ad73 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiidleservice/index.html @@ -0,0 +1,119 @@ +--- +title: nsIIdleService +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIIdleService +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIIdleService +--- +<p><span class="lang lang-en"><code>nsIIdleService </code>的定义文档是：<span class="lang lang-en"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/widget/public/nsIIdleService.idl" rel="external nofollow" title="http://mxr.mozilla.org/mozilla-central/source/widget/public/nsIIdleService.idl"><code>widget/public/nsIIdleService.idl</code></a> </span>。 It is <span class="lang lang-en"><a href="../../../../en/Interfaces/About_Scriptable_Interfaces" rel="internal">scriptable</a> </span> and <span class="lang lang-en"> <a href="../../../../en/Interfaces/About_Frozen_Interfaces" rel="internal">unfrozen</a> (hasn't changed since Mozilla 1.9a) </span>. </span></p> +<h2 id="Summary" name="Summary">概要</h2> +<p>该服务可使您监测到空闲时间，例如，用户没有进行鼠标或者键盘等操作。您可直接捕获到空闲的时间，但一般，需要注册一个监听。</p> +<p>目前<code> nsIIdleService</code> 服务在 Windows, Mac OS X, and Linux (via XScreenSaver) 等系统上都已实现。</p> +<p>实现： <code>@mozilla.org/widget/idleservice;1</code>。创建实例如：</p> +<pre class="eval">var idleService = Components.classes["@mozilla.org/widget/idleservice;1"] + .getService(Components.interfaces.nsIIdleService) +</pre> +<h2 id="Method_overview" name="Method_overview">方法预览</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#addIdleObserver.28.29">addIdleObserver</a>(in <a href="/en/nsIObserver" title="en/nsIObserver">nsIObserver</a> observer, in unsigned long time)</code></td> + </tr> + <tr> + <td><code>void <a href="#removeIdleObserver.28.29">removeIdleObserver</a>(in <a href="/en/nsIObserver" title="en/nsIObserver">nsIObserver</a> observer, in unsigned long time)</code></td> + </tr> + </tbody> +</table> +<h2 id="Attributes" name="Attributes">属性</h2> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">属性</td> + <td class="header">类型</td> + <td class="header">描述</td> + </tr> + <tr> + <td><code>idleTime</code></td> + <td><code>long</code></td> + <td>The amount of time in milliseconds that has passed since the last user activity. <em>Read only.</em></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">方法</h2> +<h3 id="addIdleObserver.28.29" name="addIdleObserver.28.29">addIdleObserver()</h3> +<p>添加一个observer，用于侦听使用者何时离开，及何时归来。</p> +<pre class="eval">void addIdleObserver( + in nsIObserver observer, + in unsigned long time +) +</pre> +<h6 id="Parameters" name="Parameters">参数 </h6> +<dl> + <dt> + <code>observer</code></dt> + <dd> + The <a href="/en/nsIObserver" title="en/nsIObserver">observer</a> to be notified.</dd> +</dl> +<dl> + <dt> + <code>time</code></dt> + <dd> + 使用者离开多少秒钟后，开始侦听。</dd> +</dl> +<h6 id="Remarks" name="Remarks">备注</h6> +<ul> + <li>observer 侦听的 subject 一直是 nsIIdleSerivce 。当空闲时， observer 的 topic 是 'idle' ， 当他回来时，将为 'back' 。侦听的参数中包含当前使用空闲的时间。</li> +</ul> +<ul> + <li>相同的 observer 可以添加两次。</li> +</ul> +<ul> + <li>大多数实现需要自己在 OS 中查询 idle 信息，侦听可能会出现延迟，这取决于在实现中查询的间隔时间的长度。当前实现中使用的是 5 秒钟的延迟时间。</li> +</ul> +<p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.2 note</div> + <div>从版本 Gecko 1.9.2 开始，增加一个新的侦听消息：‘idle-daily’ 。</div> +</div><p></p> +<h3 id="removeIdleObserver.28.29" name="removeIdleObserver.28.29">removeIdleObserver()</h3> +<p>删除observer。</p> +<pre class="eval">void removeIdleObserver( + in nsIObserver observer, + in unsigned long time +) +</pre> +<h6 id="Parameters_2" name="Parameters_2">参数</h6> +<dl> + <dt> + <code>observer</code></dt> + <dd> + the <a href="/en/nsIObserver" title="en/nsIObserver">observer</a> to be removed</dd> +</dl> +<dl> + <dt> + <code>time</code></dt> + <dd> + 消息侦听的时间（一段时间）。</dd> +</dl> +<p>备注</p> +<p>删除 observer 时，根据指定的 idle 时间来删除。如果已经添加了多个 observer ，则需要删除多次。</p> +<h2 id="Example_Code" name="Example_Code">示例：</h2> +<p>例一：</p> +<pre class="eval">var idleService = Components.classes["@mozilla.org/widget/idleservice;1"] + .getService(Components.interfaces.nsIIdleService) +setTimeout(function() { alert(idleService.idleTime) }, 1000) +// if you don't use the mouse or the keyboard after running this snippet, +// you'll see a number around 1000 alerted. +</pre> +<p>例二：</p> +<pre class="eval">var idleService = Components.classes["@mozilla.org/widget/idleservice;1"] + .getService(Components.interfaces.nsIIdleService) +var idleObserver = { + observe: function(subject, topic, data) { + alert("topic: " + topic + "\ndata: " + data); + } +}; +idleService.addIdleObserver(idleObserver, 60); // one minute +// ... +// Don't forget to remove the observer using removeIdleObserver! +idleService.removeIdleObserver(idleObserver, 60); +</pre> +<p><span class="comment">Interwiki Language Links</span></p> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsilocalfile/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsilocalfile/index.html new file mode 100644 index 0000000000..882450bf87 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsilocalfile/index.html @@ -0,0 +1,478 @@ +--- +title: nsILocalFile +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile +--- +<p> </p> + +<div class="note"> +<p>In <span title="(Firefox 14 / Thunderbird 14 / SeaMonkey 2.11)">Gecko 14</span> this Interface was merged into the <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code> interface.</p> +</div> + +<p> </p> + +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/xpcom/io/nsILocalFile.idl" rel="custom">xpcom/io/nsILocalFile.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +This interface adds methods to <code>nsIFile</code> that are particular to a file that is accessible via the local file system. +</span> + + <div style="height: 42px; position: relative; padding: 2px; width: auto;"> + + <div style="top: 22px; font-size: 11px; position: absolute; left: 0px; text-align: right; float: right; width: 100%;">66</div> + +<div style="height: 8px; top: 16px; left: 0%; background: #00dd00; position: absolute; width: 25.71428571428571%;" title="Introduced in Gecko 1.0 "></div> + +<div style="top: 0px; font-size: 11px; position: absolute; left: 0%;">Introduced</div> +<div style="top: 22px; font-size: 11px; position: absolute; left: 0%;">Gecko 1.0</div> + + <div style="height: 8px; top: 16px; left: 25.71428571428571%; background: #ff8000; position: absolute; width: 74.28571428571429%;" title="Deprecated in Gecko 14 (Firefox 14 / Thunderbird 14 / SeaMonkey 2.11)"></div> + + <div style="top: 0px; font-size: 11px; position: absolute; left: 25.71428571428571%;">Deprecated</div> + <div style="top: 22px; font-size: 11px; position: absolute; left: 25.71428571428571%;">Gecko 14</div> + +</div> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.0 </span></div> +</div><p></p> + +<p>Implemented by: <code>@mozilla.org/file/local;1</code>. To create an instance, use:</p> + +<pre class="eval">var localFile = Components.classes["@mozilla.org/file/local;1"] + .createInstance(Components.interfaces.nsILocalFile); +</pre> + +<h2 id="Method_overview" name="Method_overview">Method overview</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#appendRelativeNativePath()">appendRelativeNativePath</a>(in ACString relativeFilePath);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#appendRelativePath()">appendRelativePath</a>(in AString relativeFilePath);</code></td> + </tr> + <tr> + <td><code>ACString <a href="#getRelativeDescriptor()">getRelativeDescriptor</a>(in nsILocalFile fromFile);</code></td> + </tr> + <tr> + <td><code>void <a href="#initWithFile()">initWithFile</a>(in nsILocalFile aFile);</code></td> + </tr> + <tr> + <td><code>void <a href="#initWithNativePath()">initWithNativePath</a>(in ACString filePath);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#initWithPath()">initWithPath</a>(in AString filePath);</code></td> + </tr> + <tr> + <td><code>void <a href="#launch()">launch</a>();</code></td> + </tr> + <tr> + <td><code>PRLibraryStar <a href="#load()">load</a>();</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>FILE <a href="#openANSIFileDesc()">openANSIFileDesc</a>(in string mode);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>PRFileDescStar <a href="#openNSPRFileDesc()">openNSPRFileDesc</a>(in long flags, in long mode);</code> <span class="inlineIndicator noscript noscriptInline" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span></td> + </tr> + <tr> + <td><code>void <a href="#reveal()">reveal</a>();</code></td> + </tr> + <tr> + <td><code>void <a href="#setRelativeDescriptor()">setRelativeDescriptor</a>(in nsILocalFile fromFile, in ACString relativeDesc);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Attributes" name="Attributes">Attributes</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Attribute</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>diskSpaceAvailable</code></td> + <td><code><a href="/zh-cn/PRInt64" title="zh-cn/PRInt64">PRInt64</a></code></td> + <td>The number of bytes available to non-superuser on the disk volume containing the <code>nsILocalFile</code>. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>followLinks</code></td> + <td><code><a href="/zh-cn/PRBool" title="zh-cn/PRBool">PRBool</a></code></td> + <td> + <p>Determines whether or not the <code>nsILocalFile</code> will automatically resolve symbolic links.</p> + By default, this value is <code>false</code> on all non-UNIX systems. As of Mozilla 1.7, this attribute is ignored on UNIX systems.</td> + </tr> + <tr> + <td><code>persistentDescriptor</code></td> + <td><code><a href="/zh-cn/ACString" title="zh-cn/ACString">ACString</a></code></td> + <td> + <p>On some platforms, the value of <a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIFile#path">nsIFile.path</a> may be insufficient to uniquely identify the file on the local file system. The persistent descriptor is intended to be used whenever a <code>nsILocalFile</code> needs to be serialized to disk and later recovered. This string is not intended for display to users.</p> + <div class="blockIndicator note"><strong>Note:</strong> The value of the <code>followLinks</code> attribute is not encoded in the persistent descriptor.</div></td> + </tr> + </tbody> +</table> + +<h2 id="Constants" name="Constants">Constants</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>DELETE_ON_CLOSE</code></td> + <td><code>0x80000000</code></td> + <td>Optional parameter used by <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile#openNSPRFileDesc()">openNSPRFileDesc()</a></code>. </td> + </tr> + </tbody> +</table> + +<h2 id="Methods" name="Methods">Methods</h2> + +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="appendRelativeNativePath">appendRelativeNativePath</h3></div><p></p> + +<p>Appends a relative, native character encoding, path to the current path of the <code>nsILocalFile</code> object.</p> + +<pre class="eval">void appendRelativeNativePath( + in ACString relativeFilePath +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>relativeFilePath</code></dt> + <dd>A native relative path. For security reasons, this cannot contain '..' or cannot start with a directory separator '.'. Must be in the native file system character set.</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + +<dl> + <dt><code>NS_ERROR_FILE_UNRECOGNIZED_PATH</code></dt> + <dd>Indicates that <code>relativeFilePath</code> incorrectly begins with a path separator character or otherwise contains invalid characters.</dd> +</dl> + +<h3 id="appendRelativePath()" name="appendRelativePath()">appendRelativePath()</h3> + +<p>Appends a relative native path to the current path of the <code>nsILocalFile</code> object.</p> + +<pre class="eval">void appendRelativePath( + in AString relativeFilePath +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>relativeFilePath</code></dt> + <dd>A native relative path. For security reasons, this cannot contain '..' or cannot start with a directory separator '.' .</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + +<dl> + <dt><code>NS_ERROR_FILE_UNRECOGNIZED_PATH</code></dt> + <dd>Indicates that <code>relativeFilePath</code> incorrectly begins with a path separator character or otherwise contains invalid characters.</dd> +</dl> + +<h3 id="getRelativeDescriptor()" name="getRelativeDescriptor()">getRelativeDescriptor()</h3> + +<p>Returns a relative file path in an opaque, cross platform format. It is therefore not a native path.</p> + +<pre class="eval">ACString getRelativeDescriptor( + in nsILocalFile fromFile +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>fromFile</code></dt> + <dd>The file from which the descriptor is relative. There is no defined result if this parameter is <code>null</code>.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>An opaque string value with undefined character encoding. This string is not intended for display to users.</p> + +<p>The result returned from this method may be used with <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile#setRelativeDescriptor()">setRelativeDescriptor()</a></code> to initialize a <code>nsILocalFile</code> instance.</p> + +<h3 id="initWithFile()" name="initWithFile()">initWithFile()</h3> + +<p>Initializes this object with another file.</p> + +<pre class="eval">void initWithFile( + in nsILocalFile aFile +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>aFile</code></dt> + <dd>The file this becomes equivalent to.</dd> +</dl> + +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="initWithNativePath">initWithNativePath</h3></div><p></p> + +<p>Used to set the full path that this <code>nsILocalFile</code> references. All current settings will be reset.</p> + +<pre class="eval">void initWithNativePath( + in ACString filePath +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>filePath</code></dt> + <dd>A string that specifies a platform-specific, full path to a file or directory. Must be in the native file system character set.</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + +<dl> + <dt><code>NS_ERROR_FILE_UNRECOGNIZED_PATH</code></dt> + <dd>Indicates that FilePath is not an absolute file path.</dd> +</dl> + +<h3 id="initWithPath()" name="initWithPath()">initWithPath()</h3> + +<p>Used to set the full path that this <code>nsILocalFile</code> references. All current settings will be reset.</p> + +<pre class="eval">void initWithPath( + in AString filePath +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>filePath</code></dt> + <dd>A string that specifies a platform-specific, full path to a file or directory.</dd> +</dl> + +<h6 id="Exceptions_thrown" name="Exceptions_thrown">Exceptions thrown</h6> + +<dl> + <dt><code>NS_ERROR_FILE_UNRECOGNIZED_PATH</code></dt> + <dd>Indicates that FilePath is not an absolute file path.</dd> +</dl> + +<h3 id="launch()" name="launch()">launch()</h3> + +<p>Requests that the operating system attempt to open this file.</p> + +<pre class="eval">void launch(); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<p>None.</p> + +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="load">load</h3></div><p></p> + +<p>Returns the result of <a href="/zh-cn/PR_LoadLibrary" title="zh-cn/PR LoadLibrary"><code>PR_LoadLibrary()</code></a> on the file. The caller is responsible for calling <a href="/zh-cn/PR_UnloadLibrary" title="zh-cn/PR UnloadLibrary"><code>PR_UnloadLibrary()</code></a> on the result.</p> + +<pre class="eval">PRLibraryStar load(); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<p>None.</p> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>A pointer to a <a href="/zh-cn/PRLibrary" title="zh-cn/PRLibrary"><code>PRLibrary</code></a>.</p> + +<h6 id="Example" name="Example">Example</h6> + +<pre class="brush: cpp">#include "prlink.h" +#include "nsError.h" +#include "nsILocalFile.h" + +// Load the DLL corresponding to the given nsILocalFile... + +nsresult LoadDLL(nsILocalFile *aLocalFile) +{ + PRLibrary *dll; + nsresult rv = aLocalFile->Load(&dll); + if (NS_FAILED(rv)) + return rv; + + // Do something with the library now that it is open... + + PR_FreeLibrary(dll); + return NS_OK; +} +</pre> + +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="openANSIFileDesc">openANSIFileDesc</h3></div><p></p> + +<p>Returns the result of <code>fopen()</code> on the file. The caller is responsible for calling <code>fclose()</code> on the result.</p> + +<pre class="eval">FILE openANSIFileDesc( + in string mode +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>mode</code></dt> + <dd>An ANSI file open mode string, which will be passed to <code>fopen()</code>.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>A pointer to an ANSI <code>FILE</code> type.</p> + +<h6 id="Example" name="Example">Example</h6> + +<pre class="brush: cpp">#include <stdio.h> +#include "nsError.h" +#include "nsILocalFile.h" + +// Read the contents of a nsILocalFile... + +nsresult ReadLocalFile(nsILocalFile *aLocalFile) +{ + FILE *fp; + nsresult rv = aLocalFile->OpenANSIFileDesc("r", &fp); + if (NS_FAILED(rv)) + return rv; + + char buf[512]; + size_t n; + + while ((n = fread(buf, sizeof(buf), 1, fp)) > 0) + { + // Do something with n-byte block of data from file... + } + + if (ferror(fp) != 0) + rv = NS_ERROR_UNEXPECTED; + + fclose(fp); + return rv; +} +</pre> + +<p></p><div><span class="indicatorInHeadline noscript noscriptMethod" title="This method may only be called from C++; don't use it from JavaScript.">Native code only!</span><h3 id="openNSPRFileDesc">openNSPRFileDesc</h3></div><p></p> + +<p>Returns the result of <a href="/zh-cn/PR_Open" title="zh-cn/PR Open"><code>PR_Open()</code></a> on the file. The caller is responsible for calling <a href="/zh-cn/PR_Close" title="zh-cn/PR Close"><code>PR_Close()</code></a> on the result.</p> + +<pre class="eval">PRFileDescStar openNSPRFileDesc( + in long flags, + in long mode +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>flags</code></dt> + <dd> + <p>The <a href="/zh-cn/PR_Open" title="zh-cn/PR Open"><code>PR_Open()</code></a> flags from <code><a href="https://dxr.mozilla.org/mozilla-central/source/nsprpub/pr/include/prio.h" rel="custom">nsprpub/pr/include/prio.h</a></code>, plus optionally <code>DELETE_ON_CLOSE</code>. <code>DELETE_ON_CLOSE</code> may be implemented by removing the file (by path name) immediately after opening it, so beware of possible races; the file should be exclusively owned by this process.</p> + + <p>A bitwise combination of the following open flags:</p> + + <ul> + <li><code><strong>PR_RDONLY</strong></code> Open for reading only.</li> + <li><code><strong>PR_WRONLY</strong></code> Open for writing only.</li> + <li><code><strong>PR_RDWR</strong></code> Open for reading and writing.</li> + <li><code><strong>PR_CREATE_FILE</strong></code> If the file does not exist, the file is created. If the file exists, this flag has no effect.</li> + <li><code><strong>PR_APPEND</strong></code> The file pointer is set to the end of the file prior to each write.</li> + <li><code><strong>PR_TRUNCATE</strong></code> If the file exists, its length is truncated to 0.</li> + <li><code><strong>PR_SYNC</strong></code> If set, each write will wait for both the file data and file status to be physically updated.</li> + <li><code><strong>PR_EXCL</strong></code> With <code>PR_CREATE_FILE</code>, if the file does not exist, the file is created. If the file already exists, no action and null is returned.</li> + <li><code><strong>DELETE_ON_CLOSE</strong></code> File will be deleted when closed.</li> + </ul> + </dd> + <dt><code>mode</code></dt> + <dd>A UNIX-style file permissions value. For example, the octal value 0600 may be used to limit read and write access to the current user of the system. This parameter may be ignored on systems that do not support file permissions.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>If the file is successfully opened, returns a pointer to the <a href="/zh-cn/PRFileDesc" title="zh-cn/PRFileDesc"><code>PRFileDesc</code></a> created for the newly opened file. Returns a null pointer if the open failed.</p> + +<h6 id="Example" name="Example">Example</h6> + +<pre class="brush: cpp">#include "prio.h" +#include "nsError.h" +#include "nsILocalFile.h" + +// Read the contents of a nsILocalFile... + +nsresult ReadLocalFile(nsILocalFile *aLocalFile) +{ + PRFileDesc *fd; + nsresult rv = aLocalFile->OpenNSPRFileDesc(PR_RDONLY, 0, &fd); + if (NS_FAILED(rv)) + return rv; + + char buf[512]; + PRInt32 n; + + while ((n = PR_Read(fd, buf, sizeof(buf))) > 0) + { + // Do something with n-byte block of data from file... + } + + if (n < 0) + rv = NS_ERROR_UNEXPECTED; + + PR_Close(fd); + return rv; +} +</pre> + +<h3 id="reveal()" name="reveal()">reveal()</h3> + +<p>Ask the operating system to open the folder which contains this file or folder. This routine only works on platforms which support the ability to open a folder. See the note in the <a href="#Remarks">remarks</a> below.</p> + +<pre class="eval">void reveal(); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<p>None.</p> + +<h3 id="setRelativeDescriptor()" name="setRelativeDescriptor()">setRelativeDescriptor()</h3> + +<p>Initializes the file to the location relative to <code>fromFile</code> using a string returned by <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile#getRelativeDescriptor()">getRelativeDescriptor()</a></code>.</p> + +<pre class="eval">void setRelativeDescriptor( + in nsILocalFile fromFile, + in ACString relativeDesc +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>fromFile</code></dt> + <dd>The file to which the descriptor is relative.</dd> + <dt><code>relativeDesc</code></dt> + <dd>The relative descriptor obtained from <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile#getRelativeDescriptor()">getRelativeDescriptor()</a></code>.</dd> +</dl> + +<h2 id="Remarks" name="Remarks">Remarks</h2> + +<p>The methods <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile#initWithNativePath()">initWithNativePath()</a></code> and <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile#appendRelativeNativePath()">appendRelativeNativePath()</a></code> take string valued parameters that are encoded using the native character encoding. That means, you cannot deal with files whose name contain characters outside the default code page on Windows even though Windows 2000 or later has no problem with them. Therefore, <strong>never</strong> use these functions unless you are absolutely sure that the path passed to them is <strong>always</strong> ASCII-only. See <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code> for more information on the native character encoding.</p> + +<h2 id="See_also" name="See_also">See also</h2> + +<ul> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code></li> +</ul> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiprocess/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiprocess/index.html new file mode 100644 index 0000000000..1abc109440 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiprocess/index.html @@ -0,0 +1,283 @@ +--- +title: nsIProcess +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIProcess +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIProcess +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/xpcom/threads/nsIProcess.idl" rel="custom">xpcom/threads/nsIProcess.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +This interface represents an executable process. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)</span></div> +</div><p></p> +<p>Implemented by: <code>@mozilla.org/process/util;1</code>. To create an instance, use:</p> +<pre class="eval">var process = Components.classes["@mozilla.org/process/util;1"] + .createInstance(Components.interfaces.nsIProcess); +</pre> +<h2 id="Method_overview" name="Method_overview">Method overview</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#init()">init</a>(in nsIFile executable);</code></td> + </tr> + <tr> + <td><code>void <a href="#initWithPid()">initWithPid</a>(in unsigned long pid);</code> <span class="inlineIndicator obsolete obsoleteInline" title="(Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)">已废弃 Gecko 1.9.2</span></td> + </tr> + <tr> + <td><code>void <a href="#kill()">kill</a>();</code></td> + </tr> + <tr> + <td><code>void <a href="#run()">run</a>(in boolean blocking, [array, size_is(count)] in string args, in unsigned long count);</code></td> + </tr> + <tr> + <td><code>void <a href="#runAsync()">runAsync</a>([array, size_is(count)] in string args, in unsigned long count, [optional] in nsIObserver observer, [optional] in boolean holdWeak);</code> </td> + </tr> + <tr> + <td><code>void <a href="#runw()">runw</a>(in boolean blocking, [array, size_is(count)] in wstring args, in unsigned long count);</code> </td> + </tr> + <tr> + <td><code>void <a href="#runwAsync()">runwAsync</a>([array, size_is(count)] in wstring args, in unsigned long count, [optional] in nsIObserver observer, [optional] in boolean holdWeak);</code> </td> + </tr> + </tbody> +</table> +<h2 id="Attributes" name="Attributes">属性</h2> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">属性名称</td> + <td class="header">属性类型</td> + <td class="header">属性描述</td> + </tr> + <tr> + <td><code>exitValue</code></td> + <td><code><a href="/zh-cn/long" title="zh-cn/long">long</a></code></td> + <td>The value returned by the process upon exit. This is only valid after the process has exited. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>isRunning</code></td> + <td><code><a href="/zh-cn/boolean" title="zh-cn/boolean">boolean</a></code></td> + <td><code>true</code> if the process is running, otherwise <code>false</code>. Only accurate if the process was run with blocking disabled. <strong>Read only.</strong> </td> + </tr> + <tr> + <td><code>location</code></td> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code></code></td> + <td> + <p>The location of the executable file on disk. <strong>Read only.</strong></p> + <p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.1 note</div> + <div>This attribute is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.</div> +</div><p></p> + </td> + </tr> + <tr> + <td><code>pid</code></td> + <td><code><a href="/zh-cn/unsigned_long" title="zh-cn/unsigned long">unsigned long</a></code></td> + <td>The process ID of the process. This value is only available after the process has started; in addition, some platforms may not offer this value at all. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>processName</code></td> + <td><code><a href="/zh-cn/string" title="zh-cn/string">string</a></code></td> + <td> + <p>The name of the process. <strong>Read only.</strong></p> + <p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.1 note</div> + <div>This attribute is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.</div> +</div><p></p> + </td> + </tr> + <tr> + <td><code>processSignature</code></td> + <td><code><a href="/zh-cn/unsigned_long" title="zh-cn/unsigned long">unsigned long</a></code></td> + <td> + <p>The process signature. <strong>Read only.</strong></p> + <p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.1 note</div> + <div>This attribute is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.</div> +</div><p></p> + </td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">方法</h2> +<h3 id="init()" name="init()">init()</h3> +<p>Initializes the <code>nsIProcess</code> with the specified executable file. Once initialized, you can start the process executing by calling <code><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIProcess#run()">run()</a></code>.</p> +<p></p><div class="blockIndicator note"><strong>Note:</strong> This function does not work with application bundles on Mac OS X, see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=307463" title="nsProcess::init fails for Mac OS X application bundles (foo.app)">bug 307463</a> for details.</div><p></p> +<pre class="eval">void init( + in nsIFile executable +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>executable</code></dt> + <dd> + The <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code> executable file to be represented by the <code>nsIProcess</code> object.</dd> +</dl> +<p></p><div class="headingWithIndicator"> + <h3 id="initWithPid()">initWithPid()</h3> + <span class="indicatorInHeadline obsolete obsoleteMethod">已废弃 Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)</span> + </div><p></p> +<p>Initializes the <code>nsIProcess</code> to represent an existing process, given that process's ID.</p> +<p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.1 note</div> + <div>This method is no longer implemented as of Gecko 1.9.1, and is removed entirely in Gecko 1.9.2.</div> +</div><p></p> +<pre class="eval">void initWithPid( + in unsigned long pid +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>pid</code></dt> + <dd> + The process ID to begin to represent.</dd> +</dl> +<h3 id="kill()" name="kill()">kill()</h3> +<p>立即终止该<code>nsIProcess对象所代表的进程</code>,只在该进程是非阻塞方式启动的情况下才有效.</p> +<p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.1 note</div> + <div>在Gecko 1.9.1 (Firefox 3.5)之前版本中, 该方法在Windows和Mac OS X下无效.目前此bug已经修复.</div> +</div><p></p> +<pre class="eval">void kill(); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<p>无.</p> +<h3 id="run()" name="run()">run()</h3> +<p>开始执行进程.</p> +<p></p><div class="blockIndicator geckoMinVer standardNote"> + <div style="text-align: center; font-weight: bold; padding-bottom: 0.5em;">Gecko 1.9.1 note</div> + <div>在Gecko 1.9.1 (Firefox 3.5)之前版本中,该方法会返回一个新执行进程的进程ID,目前已经不会返回任何值.</div> +</div><p></p> +<pre class="eval">void run( + in boolean blocking, + [array, size_is(count)] in string args, + in unsigned long count +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>blocking</code></dt> + <dd> + 如果为<code>true</code>,则该方法会阻塞,直到所打开的进程关闭为止,如果为<code>false</code>,则该方法会立即返回.</dd> + <dt> + <code>args</code></dt> + <dd> + An array of <code>count</code> arguments, using the native character set, to be passed to the executable on its command line.</dd> + <dt> + <code>count</code></dt> + <dd> + 参数<code>args中的参数个数</code>.</dd> +</dl> +<p></p><h3 id="runAsync()">runAsync()</h3><p></p> +<p>Asynchronously runs the process with which the object was initialized, optionally calling an observer when the process finishes running.</p> +<pre class="eval">void runAsync( + [array, size_is(count)] in string args, + in unsigned long count, + in nsIObserver observer, <span class="inlineIndicator optional optionalInline">可选</span> + in boolean holdWeak <span class="inlineIndicator optional optionalInline">可选</span> +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>args</code></dt> + <dd> + An array of arguments to pass into the process, using the native character set. This array must have <code>count</code> entries.</dd> + <dt> + <code>count</code></dt> + <dd> + The number of arguments passed in the <code>args</code> array.</dd> + <dt> + <code>observer</code> <span class="inlineIndicator optional optionalInline">可选</span></dt> + <dd> + An observer that will be notified when the process exits. The observer will receive this <code>nsIProcess</code> instance as the subject and "process-finished" or "process-failed" as the topic. The observer will be notified on the main thread.</dd> + <dt> + <code>holdWeak</code> <span class="inlineIndicator optional optionalInline">可选</span></dt> + <dd> + If <code>true</code>, a <a class="internal" href="/zh-cn/Weak_reference" title="zh-cn/Weak reference">weak reference</a> is used to hold the observer.</dd> + <dd> + </dd> +</dl> +<p></p><h3 id="runw()">runw()</h3><p></p> +<p>Executes the file this object was initialized with.</p> +<pre class="eval">void runw( + in boolean blocking, + [array, size_is(count)] in wstring args, + in unsigned long count +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>blocking</code></dt> + <dd> + If <code>true</code>, this method will block until the process terminates; if <code>false</code>, the method returns immediately.</dd> + <dt> + <code>args</code></dt> + <dd> + An array of <code>count</code> arguments, using UTF-16, to be passed to the executable on its command line.</dd> + <dt> + <code>count</code></dt> + <dd> + The number of arguments in the <code>args</code> array.</dd> +</dl> +<p></p><h3 id="runwAsync()">runwAsync()</h3><p></p> +<p>Asynchronously runs the process with which the object was initialized, optionally calling an observer when the process finishes running.</p> +<pre class="eval">void runwAsync( + [array, size_is(count)] in wstring args, + in unsigned long count, + in nsIObserver observer, <span class="inlineIndicator optional optionalInline">可选</span> + in boolean holdWeak <span class="inlineIndicator optional optionalInline">可选</span> +); +</pre> +<h6 id="Parameters" name="Parameters">Parameters</h6> +<dl> + <dt> + <code>args</code></dt> + <dd> + An array of arguments to pass into the process, using UTF-16. This array must have <code>count</code> entries.</dd> + <dt> + <code>count</code></dt> + <dd> + The number of arguments passed in the <code>args</code> array.</dd> + <dt> + <code>observer</code> <span class="inlineIndicator optional optionalInline">可选</span></dt> + <dd> + An observer that will be notified when the process exits. The observer will receive this <code>nsIProcess</code> instance as the subject and "process-finished" or "process-failed" as the topic. The observer will be notified on the main thread.</dd> + <dt> + <code>holdWeak</code> <span class="inlineIndicator optional optionalInline">可选</span></dt> + <dd> + If <code>true</code>, a <a class="internal" href="/zh-cn/Weak_reference" title="zh-cn/Weak reference">weak reference</a> is used to hold the observer.</dd> +</dl> +<h2 id="See_also" name="See_also">Example</h2> +<pre class="brush: js">// create an nsILocalFile for the executable +var file = Components.classes["@mozilla.org/file/local;1"] + .createInstance(Components.interfaces.nsILocalFile); +file.initWithPath("c:\\myapp.exe"); + +// create an nsIProcess +var process = Components.classes["@mozilla.org/process/util;1"] + .createInstance(Components.interfaces.nsIProcess); +process.init(file); + +// Run the process. +// If first param is true, calling thread will be blocked until +// called process terminates. +// Second and third params are used to pass command-line arguments +// to the process. +var args = ["argument1", "argument2"]; +process.run(false, args, args.length); +</pre> +<h2 id="See_also" name="See_also">See also</h2> +<ul> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFile" title="">nsIFile</a></code></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsILocalFile" title="">nsILocalFile</a></code></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIProcess2" title="">nsIProcess2</a></code> <span class="inlineIndicator obsolete obsoleteInline" title="(Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)">已废弃 Gecko 1.9.2</span></li> +</ul> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiprompt/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiprompt/index.html new file mode 100644 index 0000000000..9bd2106964 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiprompt/index.html @@ -0,0 +1,55 @@ +--- +title: nsIPrompt +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIPrompt +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIPrompt +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/netwerk/base/public/nsIPrompt.idl" rel="custom">netwerk/base/public/nsIPrompt.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +This is the prompt interface which can be used without knowledge of a parent window. The parentage is hidden by the <code>GetInterface</code> though which it is obtained. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)</span></div> +</div><p></p> +<div class="note"> + <strong>注:</strong> 本接口基本等价于<code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService" title="">nsIPromptService</a></code>,只是没有parent <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code>这个参数.为了避免重复的文档,下面的所有方法都链接到了<code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService" title="">nsIPromptService</a></code>.如果你准备使用这个接口,一定要删除那些方法中的<code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code>参数.</div> +<p>Normally you would use the prompt service as it is more flexible, but sometimes a callback will request an <code>nsIPrompt</code> via <code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIInterfaceRequestor#getInterface()">nsIInterfaceRequestor.getInterface()</a></code>. To get an instance, call the <code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIWindowWatcher#getNewPrompter()">nsIWindowWatcher.getNewPrompter()</a></code>.</p> +<h2 id="Method_overview" name="Method_overview">方法概述</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#alert()" title="en/XPCOM_Interface_Reference/nsIPromptService#alert()">alert</a>(in wstring dialogTitle, in wstring text);</code></td> + </tr> + <tr> + <td><code>void <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#alertCheck()" title="en/XPCOM_Interface_Reference/nsIPromptService#alertCheck()">alertCheck</a>(in wstring dialogTitle, in wstring text, in wstring checkMsg, inout boolean checkValue);</code></td> + </tr> + <tr> + <td><code>boolean <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#confirm()" title="en/XPCOM_Interface_Reference/nsIPromptService#confirm()">confirm</a>(in wstring dialogTitle, in wstring text);</code></td> + </tr> + <tr> + <td><code>boolean <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#confirmCheck()" title="en/XPCOM_Interface_Reference/nsIPromptService#confirmCheck()">confirmCheck</a>(in wstring dialogTitle, in wstring text, in wstring checkMsg, inout boolean checkValue);</code></td> + </tr> + <tr> + <td><code>PRInt32 <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#confirmEx()" title="en/XPCOM_Interface_Reference/nsIPromptService#confirmEx()">confirmEx</a>(in wstring dialogTitle, in wstring text, in unsigned long buttonFlags, in wstring button0Title, in wstring button1Title, in wstring button2Title, in wstring checkMsg, inout boolean checkValue);</code></td> + </tr> + <tr> + <td><code>boolean <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#prompt()" title="en/XPCOM_Interface_Reference/nsIPromptService#prompt()">prompt</a>(in wstring dialogTitle, in wstring text, inout wstring value, in wstring checkMsg, inout boolean checkValue);</code></td> + </tr> + <tr> + <td><code>boolean <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#promptPassword()" title="en/XPCOM_Interface_Reference/nsIPromptService#promptPassword()">promptPassword</a>(in wstring dialogTitle, in wstring text, inout wstring password, in wstring checkMsg, inout boolean checkValue);</code></td> + </tr> + <tr> + <td><code>boolean <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#promptUsernameAndPassword()" title="en/XPCOM_Interface_Reference/nsIPromptService#promptUsernameAndPassword()">promptUsernameAndPassword</a>(in wstring dialogTitle, in wstring text, inout wstring username, inout wstring password, in wstring checkMsg, inout boolean checkValue);</code></td> + </tr> + <tr> + <td><code>boolean <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#select()" title="en/XPCOM_Interface_Reference/nsIPromptService#select()">select</a>(in wstring dialogTitle, in wstring text, in PRUint32 count, [array, size_is(count)] in wstring selectList, out long outSelection);</code></td> + </tr> + </tbody> +</table> +<h2 id="Constants" name="Constants">常量</h2> +<p><code>nsIPrompt中的</code>按钮标识同样等同于<code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#Constants">nsIPromptService.Constants</a></code>中定义的那些.示例代码可以在这里找到: <a href="/zh-CN/docs/XPCOM_Interface_Reference/nsIPromptService#Using_the_button_flags" title="en/XPCOM_Interface_Reference/nsIPromptService#Using_the_button_flags">使用按钮标识</a></p> +<h2 id="相关链接">相关链接</h2> +<p><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService" title="">nsIPromptService</a></code></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsipromptservice/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsipromptservice/index.html new file mode 100644 index 0000000000..b194faca6b --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsipromptservice/index.html @@ -0,0 +1,696 @@ +--- +title: nsIPromptService +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIPromptService +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/embedding/components/windowwatcher/public/nsIPromptService.idl" rel="custom">embedding/components/windowwatcher/public/nsIPromptService.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;">该接口用来显示一些简单的对话框.在chrome上下文,你应该使用该接口的所属方法来替代常规的DOM方法,例如 <a href="/zh-CN/docs/Web/API/Window/alert" title='显示一个警告对话框,上面显示有指定的文本内容以及一个"确定"按钮。'><code>window.alert</code></a>, <a href="/zh-CN/docs/Web/API/Window/confirm" title="Window.confirm() 方法显示一个具有一个可选消息和两个按钮(确定和取消)的模态对话框 。"><code>window.confirm</code></a>, 等.</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.7.5 </span></div> +</div><p></p> +<p>You can define access keys (or keyboard shortcuts) for buttons by including an ampersand ("&") in front of the character that should be the access key for that button. If you need to include an ampersand in the button's text, use two of them, like this: "&&".</p> +<div class="note"> + <strong>Note:</strong> Some of these interface methods use <code>out</code> and <code>inout</code> parameters. In C++, <code>out</code> parameters are pointers. For JavaScript, they are extra work, as you can't use an <code>out</code> parameter directly. You need to wrap them in a temporary object, which can be either empty or have a <code>value</code> property set to the <code>out</code> parameter type. For more information on out parameters and JavaScript refer to <a href="/zh-cn/Working_with_out_parameters" title="zh-cn/Working with out parameters">Working with out parameters</a>.</div> +<p>该接口由: <code>@mozilla.org/embedcomp/prompt-service;1</code> 组件实现,下面的代码可以得到一个promptService对象实例:</p> +<pre>var promptService = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); +</pre> +<h2 id="Method_overview" name="Method_overview">方法概述</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="#alert()">alert</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText);</code></td> + </tr> + <tr> + <td><code>void <a href="#alertCheck()">alertCheck</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText, in wstring aCheckMsg, inout boolean aCheckState);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#confirm()">confirm</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#confirmCheck()">confirmCheck</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText, in wstring aCheckMsg, inout boolean aCheckState);</code></td> + </tr> + <tr> + <td><code>PRInt32 <a href="#confirmEx()">confirmEx</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent,in wstring aDialogTitle,in wstring aText, in unsigned long aButtonFlags,in wstring aButton0Title, in wstring aButton1Title,in wstring aButton2Title,in wstring aCheckMsg, inout boolean aCheckState);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#prompt()">prompt</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText, inout wstring aValue, in wstring aCheckMsg, inout boolean aCheckState);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#promptUsernameAndPassword()">promptUsernameAndPassword</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText, inout wstring aUsername, inout wstring aPassword, in wstring aCheckMsg, inout boolean aCheckState);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#promptPassword()">promptPassword</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText, inout wstring aPassword, in wstring aCheckMsg, inout boolean aCheckState);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#select()">select</a>(in <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindow" title="">nsIDOMWindow</a></code> aParent, in wstring aDialogTitle, in wstring aText, in PRUint32 aCount, [array, size_is(aCount)] in wstring aSelectList, out long aOutSelection);</code></td> + </tr> + </tbody> +</table> +<h2 id="Constants" name="Constants">常量</h2> +<p>The following flags are combined to form the <code>aButtonFlags</code> parameter passed to <a href="#confirmEx">confirmEx</a>. All flags are defined as <code>unsigned long</code> constants and can be accessed as <code>Components.interfaces.nsIPromptService.<em>flagname</em></code> from JavaScript and as nsIPromptService::<code><em>flagname</em></code> from C++.</p> +<h3 id="Button_position_flags">Button position flags</h3> +<p>On Linux and Mac, button 2 is on the left of the prompt, while buttons 1 and 0 are on the right. On Windows and OS/2, the buttons are centred in the order 0, 2, 1.</p> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>BUTTON_POS_0</code></td> + <td><code>1</code></td> + <td>This is usually the button used to confirm the prompt. It typically has the label "OK", "Yes" or "Save".</td> + </tr> + <tr> + <td><code>BUTTON_POS_1</code></td> + <td><code>256</code></td> + <td>This is the button used to cancel the prompt. It typically has the label "Cancel" or "No". It is equivalent to pressing the Escape key (or Cmd+. on the Mac), or closing the window through the OS controls.</td> + </tr> + <tr> + <td><code>BUTTON_POS_2</code></td> + <td><code>65536</code></td> + <td>This button can be used to give the user a choice of options, but still allowing the user to cancel the prompt. For instance, it might have the label "Don't Save".</td> + </tr> + </tbody> +</table> +<h3 id="Button_title_flags">Button title flags</h3> +<p>These flags are used along with <a href="#Button_position_flags">Button position flags</a> to set the labels of buttons in the prompt.</p> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>BUTTON_TITLE_OK</code></td> + <td><code>1</code></td> + <td rowspan="7"> These flags are used to select standard labels from the user's current locale.</td> + </tr> + <tr> + <td><code>BUTTON_TITLE_CANCEL</code></td> + <td><code>2</code></td> + </tr> + <tr> + <td><code>BUTTON_TITLE_YES</code></td> + <td><code>3</code></td> + </tr> + <tr> + <td><code>BUTTON_TITLE_NO</code></td> + <td><code>4</code></td> + </tr> + <tr> + <td><code>BUTTON_TITLE_SAVE</code></td> + <td><code>5</code></td> + </tr> + <tr> + <td><code>BUTTON_TITLE_DONT_SAVE</code></td> + <td><code>6</code></td> + </tr> + <tr> + <td><code>BUTTON_TITLE_REVERT</code></td> + <td><code>7</code></td> + </tr> + <tr> + <td><code>BUTTON_TITLE_IS_STRING</code></td> + <td><code>127</code></td> + <td>This flag indicates that the label is passed as a separate string. Use this for labels that don't match one of the constants above.</td> + </tr> + </tbody> +</table> +<h3 id="Button_default_flags">Button default flags</h3> +<p>These flags are used to select which button is the default.</p> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td>BUTTON_POS_0_DEFAULT</td> + <td>0</td> + <td> </td> + </tr> + <tr> + <td>BUTTON_POS_1_DEFAULT</td> + <td>16777216</td> + <td> </td> + </tr> + <tr> + <td>BUTTON_POS_2_DEFAULT</td> + <td>33554432</td> + <td> </td> + </tr> + </tbody> +</table> +<h3 id="BUTTON_DELAY_ENABLE">BUTTON_DELAY_ENABLE</h3> +<p><code>BUTTON_DELAY_ENABLE</code> causes the buttons to be initially disabled. They are enabled after a timeout expires. The implementation may interpret this loosely, as the intent is to ensure that the user does not click through a security dialog too quickly. Strictly speaking, the implementation could choose to ignore this flag. A delay can be useful not only to give the user more time to think before acting, but also as a countermeasure against malicious web sites that intentionally create a race condition whereby the user intends to click or type a key responding, for example, to the web site's prompt but the security dialog pops up unexpectedly and its button is unintentionally activated.</p> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td>BUTTON_DELAY_ENABLE</td> + <td>67108864</td> + <td> </td> + </tr> + </tbody> +</table> +<h3 id="Standard_Buttons_flags">Standard Buttons flags</h3> +<table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>STD_OK_CANCEL_BUTTONS</code></td> + <td>513</td> + <td> + <p>selects the standard set of OK/Cancel buttons.</p> + <code>(BUTTON_TITLE_OK *BUTTON_POS_0) +(BUTTON_TITLE_CANCEL * BUTTON_POS_1)</code></td> + </tr> + <tr> + <td><code>STD_YES_NO_BUTTONS</code></td> + <td>1027</td> + <td> + <p>selects the standard set of Yes/No buttons.</p> + <code>(BUTTON_TITLE_YES *BUTTON_POS_0) +(BUTTON_TITLE_NO * BUTTON_POS_1)</code></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">方法</h2> +<h3 id="alert()">alert()</h3> +<p><code>alert</code> 方法显示一个警告对话框,包含一个确认按钮. 除了可以设置对话框的标题以外,效果和<a href="/zh-CN/docs/Web/API/Window/alert" title='显示一个警告对话框,上面显示有指定的文本内容以及一个"确定"按钮。'><code>window.alert</code></a>全都相同 . 在chrome上下文,你应该使用该xpcom方法来替代<code>window.alert</code>.</p> +<pre>void alert( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> +</dl> +<p>代码示例:<a href="#alert_example">alert_example</a>.</p> +<h3 id="alertCheck()">alertCheck()</h3> +<p>显示一个警告对话框,包含一个确认按钮和一个复选框.</p> +<pre>void alertCheck( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + in wstring aCheckMsg, + inout boolean aCheckState +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>..</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aCheckMsg</code></dt> + <dd> + 复选框的说明文字.</dd> + <dt> + <code>aCheckState</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.</dd> +</dl> +<p>代码示例:<a href="#alertCheck_example">alertCheck_example</a>.</p> +<h3 id="confirm()">confirm()</h3> +<p>显示一个确认对话框,包含一个确认按钮和一个取消按钮.</p> +<pre>boolean confirm( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 点确定按钮返回 <code>true</code> , 点取消按钮返回 <code>false</code></dd> +</dl> +<p>代码示例:<a href="#confirm_example">confirm_example</a>.</p> +<h3 id="confirmCheck()">confirmCheck()</h3> +<p>显示一个对话框,包含一个确认按钮,一个取消按钮和一个复选框.</p> +<p>代码示例:<a href="#confirm_example">confirm_example</a>.</p> +<pre>boolean confirmCheck( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + in wstring aCheckMsg, + inout boolean aCheckState +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aCheckMsg</code></dt> + <dd> + 复选框的说明文字.</dd> + <dt> + <code>aCheckState</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 点确定按钮返回 <code>true</code> , 点取消按钮返回 <code>false</code></dd> +</dl> +<h3 id="confirmEx()">confirmEx()</h3> +<p>Puts up a dialog with up to 3 buttons and an optional, labeled checkbox.</p> +<p>The Buttons are numbered 0 - 2. The implementation can decide what order the buttons appear in, and it may not be simply right-to-left (2, 1, 0) or left-to-right (0, 1, 2). See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=624043" title="nsIPromptService.confirmEx : buttons show up in the order 0,2,1 instead of 0,1,2">bug 624043</a> for more on this. Button 0 is the default button unless one of the Button Default Flags is specified (see <a href="/zh-cn/XPCOM_Interface_Reference/nsIPromptService#Button_default_flags" title="https://developer.mozilla.org/zh-cn/XPCOM_Interface_Reference/nsIPromptService#Button_default_flags">Button default flags</a>).</p> +<p>A button may use a predefined title, specified by one of the Button Title Flags values. Each title value can be multiplied by a position value to assign the title to a particular button. If BUTTON_TITLE_IS_STRING is used for a button, the string parameter for that button will be used. If the value for a button position is zero, the button will not be shown.</p> +<p>The following Example creates a Dialog with an OK button an an custom button description.</p> +<p><code>aButtonFlags = (BUTTON_POS_0) * (BUTTON_TITLE_OK) +<br> + (BUTTON_POS_1) * (BUTTON_TITLE_IS_STRING) +<br> + BUTTON_POS_1_DEFAULT; </code></p> +<div class="note"> + confirmEx always returns 1 if the user closes the window using the close button in the titlebar! <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=345067" title="Issues with prompt service's confirmEx - confirmEx always returns 1 when user closes dialog window using the X button in titlebar">bug 345067</a></div> +<pre>PRInt32 confirmEx( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + in unsigned long aButtonFlags, + in wstring aButton0Title, + in wstring aButton1Title, + in wstring aButton2Title, + in wstring aCheckMsg, + inout boolean aCheckState +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aButtonFlags</code></dt> + <dd> + <code>aButtonFlags</code> is a combination of <a href="#Button_flags">Button flags</a> as described in <a href="#Using_the_button_flags">Using the button flags</a> below.</dd> + <dt> + <code>aButton0Title</code></dt> + <dd> + caption displayed for button 0 if<code>(BUTTON_TITLE_IS_STRING*</code><code>BUTTON_TITLE_POS_0)</code> flags are set in aButtonFlags</dd> + <dt> + <code>aButton1Title</code></dt> + <dd> + caption displayed for button 1 if<code>(BUTTON_TITLE_IS_STRING*</code><code>BUTTON_TITLE_POS_1)</code> flags are set in aButtonFlags</dd> + <dt> + <code>aButton2Title</code></dt> + <dd> + caption displayed for button 2 if<code>(BUTTON_TITLE_IS_STRING*</code><code>BUTTON_TITLE_POS_2)</code> flags are set in aButtonFlags</dd> + <dt> + <code>aCheckMsg</code></dt> + <dd> + 复选框的说明文字. 如果值设为Null,则复选框不会显示.</dd> + <dt> + <code>aCheckState</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 按下按钮的索引.</dd> +</dl> +<h3 id="prompt()">prompt()</h3> +<p>显示一个对话框,包含一个文本框,一个可选的复选框.</p> +<p>代码示例:<a href="#prompt_example">prompt_example</a>.</p> +<pre>boolean prompt( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + inout wstring aValue, + in wstring aCheckMsg, + inout boolean aCheckState +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aValue</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性值就是文本输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下文本输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.</dd> + <dt> + <code>aCheckMsg</code></dt> + <dd> + 复选框的说明文字. 如果值设为Null,则复选框不会显示.</dd> + <dt> + <code>aCheckState</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 点确定按钮返回 <code>true</code> , 点取消按钮返回 <code>false</code></dd> +</dl> +<h3 id="promptUsernameAndPassword()">promptUsernameAndPassword()</h3> +<p>显示一个对话框,内部包含一个文本输入框,一个密码输入框,和一个可选的复选框.</p> +<p>代码示例:<a href="#promptUsernameAndPassword_example">promptUsernameAndPassword_example</a>.</p> +<pre>boolean promptUsernameAndPassword( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + inout wstring aUsername, + inout wstring aPassword, + in wstring aCheckMsg, + inout boolean aCheckState +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aUsername</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性值就是用户名输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下用户名输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.</dd> + <dt> + <code>aPassword</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性值就是密码输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下密码输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.</dd> + <dt> + <code>aCheckMsg</code></dt> + <dd> + 复选框的说明文字. 如果值设为Null,则复选框不会显示.</dd> + <dt> + <code>aCheckState</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 点确定按钮返回 <code>true</code> , 点取消按钮返回 <code>false</code></dd> +</dl> +<h3 id="promptPassword()">promptPassword()</h3> +<p>显示一个对话框,包含一个密码框,一个可选的复选框.</p> +<p>代码示例:<a href="#promptPassword_example">promptPassword_example</a>.</p> +<pre>boolean promptPassword( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + inout wstring aPassword, + in wstring aCheckMsg, + inout boolean aCheckState +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aPassword</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性值就是密码输入框的的初始值.当用户点击确认按钮关闭对话框时,变量的value属性会存储下密码输入框的最后确定值.其他方法关闭对话框时,变量的value属性值不会改变.该变量初始化时可以包含一个类型为字符串值的value属性或者是空对象.</dd> + <dt> + <code>aCheckMsg</code></dt> + <dd> + 复选框的说明文字. 如果值设为Null,则复选框不会显示.</dd> + <dt> + <code>aCheckState</code></dt> + <dd> + 该变量是一个对象引用,当对话框打开时,变量的value属性控制了复选框的初始选择状态.当对话框关闭时,变量的value属性会存储下复选框的最后选择状态.该变量初始化时可以包含一个类型为布尔值的value属性或者是空对象.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 点确定按钮返回 <code>true</code> , 点取消按钮返回 <code>false</code></dd> +</dl> +<h3 id="select()">select()</h3> +<p>显示一个对话框,包含一个单项选择的字符串列表.</p> +<p>代码示例:<a href="#select_example">select_example</a>.</p> +<pre>boolean select( + in nsIDOMWindow aParent, + in wstring aDialogTitle, + in wstring aText, + in PRUint32 aCount, + [array, size_is(aCount)] in wstring aSelectList, + out long aOutSelection +); +</pre> +<dl> + <dt> + <code>aParent</code></dt> + <dd> + 对话框的父窗口,如果该值设为 <code>null</code>,则父窗口为当前激活的窗口 <code>nsIWindowWatcher.activeWindow</code>.</dd> + <dt> + <code>aDialogTitle</code></dt> + <dd> + 对话框的标题文字.</dd> + <dt> + <code>aText</code></dt> + <dd> + 对话框的内容文字.</dd> + <dt> + <code>aCount</code></dt> + <dd> + 参数aSelectList的数组长度.</dd> + <dt> + <code>aSelectList</code></dt> + <dd> + 构成字符串列表的字符串数组.</dd> + <dt> + <code>aOutSelection</code></dt> + <dd> + 该变量是一个对象引用,当用户选择某个项目后,变量的value属性值存储了用户所选列表项目的索引值.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<dl> + <dd> + 点确定按钮返回 <code>true</code> , 点取消按钮返回 <code>false</code></dd> +</dl> +<h2 id="代码示例">代码示例</h2> +<p> </p> +<h3 id="alert_example">alert example</h3> +<p><a href="#alert()">alert()</a> 显示一个简单的对话框.</p> +<p><img alt="" class="internal" src="/@api/deki/files/4072/=AlertExample.png" style="width: 365px; height: 129px;"></p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +prompts.alert(null, "Title of this Dialog", "Hello! You have now been alerted."); +</pre> +<h3 id="alertCheck_example">alertCheck example</h3> +<p><a href="#alertCheck()">alertCheck()</a> 显示一个包含复选框的对话框</p> +<p><img alt="" class="internal" src="/@api/deki/files/4073/=AlertCheckExample.png" style="width: 365px; height: 152px;"></p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var check = {value: false}; // default the checkbox to false + +prompts.alertCheck(null, "Title of this Dialog", "Hello! You have now been alerted.", + "And this is a checkbox", check); + +// check.value is now true if the box was checked and false if the box was cleared +</pre> +<h3 id="confirm_example">confirm example</h3> +<p><a href="#confirm()">confirm()</a> 显示一个提示框,内部包含一个确认按钮和一个取消按钮.</p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var result = prompts.confirm(null, "Title of this Dialog", "Are you sure?"); + +// result is now true if OK was clicked, and false if cancel was clicked +</pre> +<h3 id="confirmCheck_example">confirmCheck example</h3> +<p><a href="#confirmCheck">confirmCheck</a> 显示一个提示框,内部包含一个确认按钮,一个取消按钮,一个复选框.</p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var check = {value: true}; // default the checkbox to true + +var result = prompts.confirmCheck(null, "Title of this Dialog", "Are you sure?", + "Don't ask again", check); + +// check.value is now true if the box was checked AND OK was pressed, false if +// the box was cleared AND OK was pressed, and is the default of true if Cancel was pressed. +</pre> +<h3 id="confirmEx_example">confirmEx example</h3> +<p><a href="#confirmEx()">confirmEx()</a> 显示一个对话框,内部包含三个或三个以下的按纽,和一个可选的复选框.</p> +<p><img alt="" class="internal" src="/@api/deki/files/4075/=confirmExExample.png" style="width: 365px; height: 129px;"></p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var check = {value: false}; // default the checkbox to false + +var flags = prompts.BUTTON_POS_0 * prompts.BUTTON_TITLE_SAVE + + prompts.BUTTON_POS_1 * prompts.BUTTON_TITLE_IS_STRING + + prompts.BUTTON_POS_2 * prompts.BUTTON_TITLE_CANCEL; +// This value of flags will create 3 buttons. The first will be "Save", the +// second will be the value of aButtonTitle1, and the third will be "Cancel" + +var button = prompts.confirmEx(null, "Title of this Dialog", "What do you want to do?", + flags, "", "Button 1", "", null, check); + +// The checkbox will be hidden, and button will contain the index of the button pressed, +// 0, 1, or 2. +</pre> +<h3 id="prompt_example">prompt example</h3> +<p><a href="#prompt()">prompt()</a> 显示一个对话框,内部包含一个文本输入框.</p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var check = {value: false}; // default the checkbox to false + +var input = {value: "Bob"}; // default the edit field to Bob + +var result = prompts.prompt(null, "Title", "What is your name?", input, null, check); + +// result is true if OK is pressed, false if Cancel. input.value holds the value of the edit field if "OK" was pressed. +</pre> +<h3 id="promptUsernameAndPassword_example">promptUsernameAndPassword example</h3> +<p><a href="#promptUsernameAndPassword()">promptUsernameAndPassword()</a> 显示一个对话框,内部包含一个文本输入框,一个密码输入框和一个可选的复选框.</p> +<p><img alt="" class="internal" src="/@api/deki/files/4076/=promptUsernameAndPasswordExample.png" style="width: 365px; height: 200px;"></p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var username = {value: "user"}; // default the username to user + +var password = {value: "pass"}; // default the password to pass + +var check = {value: true}; // default the checkbox to true + +var result = prompts.promptUsernameAndPassword(null, "Title", "Enter username and password:", + username, password, "Save", check); + +// result is true if OK was pressed, false if cancel was pressed. username.value, +// password.value, and check.value are set if OK was pressed. +</pre> +<h3 id="promptPassword_example">promptPassword example</h3> +<p><a href="#promptPassword()">promptPassword()</a> 显示一个对话框,内部包含一个密码输入框和一个可选的复选框.</p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var password = {value: "pass"}; // default the password to pass + +var check = {value: true}; // default the checkbox to true + +var result = prompts.promptPassword(null, "Title", "Enter password:", password, null, check); + +// result is true if OK was pressed, false if cancel was pressed. password.value is +// set if OK was pressed. The checkbox is not displayed. +</pre> +<h3 id="select_example">select example</h3> +<p><a href="#select()">select()</a> 显示一个对话框,内部是一个包含多个选项的列表框.</p> +<p><img alt="" class="internal" src="/@api/deki/files/4074/=selectExample.png" style="width: 333px; height: 196px;"></p> +<pre class="brush: js">var prompts = Components.classes["@mozilla.org/embedcomp/prompt-service;1"] + .getService(Components.interfaces.nsIPromptService); + +var items = ["Hello", "Welcome", "Howdy", "Hi", ":)"]; // list items + +var selected = {}; + +var result = prompts.select(null, "Title", "What greeting do you want?", items.length, + items, selected); + +// result is true if OK was pressed, false if cancel. selected is the index of the item array +// that was selected. Get the item using items[selected.value]. +</pre> +<h2 id="See_also" name="See_also">相关链接</h2> +<ul> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIPrompt" title="">nsIPrompt</a></code></li> + <li><a href="/zh-cn/Working_with_out_parameters" title="zh-cn/Working with out parameters">Working with out parameters</a></li> +</ul> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiscriptableunicodeconverter/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiscriptableunicodeconverter/index.html new file mode 100644 index 0000000000..fe406f1bba --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiscriptableunicodeconverter/index.html @@ -0,0 +1,609 @@ +--- +title: nsIScriptableUnicodeConverter +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIScriptableUnicodeConverter +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIScriptableUnicodeConverter +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/intl/uconv/idl/nsIScriptableUConv.idl" rel="custom">intl/uconv/idl/nsIScriptableUConv.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +This interface is a Unicode encoder for use by scripts. +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)</span></div> +</div><p></p> +<p>Implemented by: <code>@mozilla.org/intl/scriptableunicodeconverter</code>. To create an instance, use:</p> +<pre class="eval">var converter = Components.classes["@mozilla.org/intl/scriptableunicodeconverter"] + .createInstance(Components.interfaces.nsIScriptableUnicodeConverter); +</pre> +<h2 id="Method_overview" name="Method_overview">Method overview</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>ACString <a href="/zh-cn/XPCOM_Interface_Reference/nsIScriptableUnicodeConverter#ConvertFromUnicode()" title="zh-cn/nsIScriptableUnicodeConverter#ConvertFromUnicode()">ConvertFromUnicode</a>(in AString aSrc);</code></td> + </tr> + <tr> + <td><code>ACString <a href="/zh-cn/XPCOM_Interface_Reference/nsIScriptableUnicodeConverter#Finish()" title="zh-cn/nsIScriptableUnicodeConverter#Finish()">Finish</a>();</code></td> + </tr> + <tr> + <td><code>AString <a href="/zh-cn/XPCOM_Interface_Reference/nsIScriptableUnicodeConverter#ConvertToUnicode()" title="zh-cn/nsIScriptableUnicodeConverter#ConvertToUnicode()">ConvertToUnicode</a>(in ACString aSrc);</code></td> + </tr> + <tr> + <td><code>AString <a href="/zh-cn/XPCOM_Interface_Reference/nsIScriptableUnicodeConverter#convertFromByteArray()" title="zh-cn/nsIScriptableUnicodeConverter#convertFromByteArray()">convertFromByteArray</a>([const,array,size_is(aCount)] in octet aData, in unsigned long aCount);</code></td> + </tr> + <tr> + <td><code>void <a href="/zh-cn/XPCOM_Interface_Reference/nsIScriptableUnicodeConverter#convertToByteArray()" title="zh-cn/nsIScriptableUnicodeConverter#convertToByteArray()">convertToByteArray</a>(in AString aString,[optional] out unsigned long aLen,[array, size_is(aLen),retval] out octet aData);</code></td> + </tr> + <tr> + <td><code><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIInputStream" title="">nsIInputStream</a></code> <a href="/zh-cn/XPCOM_Interface_Reference/nsIScriptableUnicodeConverter#convertToInputStream()" title="zh-cn/nsIScriptableUnicodeConverter#convertToInputStream()">convertToInputStream</a>(in AString aString);</code></td> + </tr> + </tbody> +</table> +<h2 id="Attributes">Attributes</h2> +<table class="standard-table" style="width: auto;"> + <tbody> + <tr> + <td class="header">Attribute</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>charset</code></td> + <td><code>string</code></td> + <td>Current character set. Throws <code>NS_ERROR_UCONV_NOCONV</code> if the requested charset is not supported.</td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">Methods</h2> +<h3 id="ConvertFromUnicode()" name="ConvertFromUnicode()">ConvertFromUnicode()</h3> +<p>Converts the data from Unicode to one Charset. Returns the converted string. After converting, Finish should be called and its return value appended to this return value.</p> +<pre class="eval">ACString ConvertFromUnicode( + in AString aSrc +); +</pre> +<h3 id="Finish()">Finish()</h3> +<p>Returns the terminator string. Should be called after ConvertFromUnicode() and appended to that function's return value.</p> +<pre>ACString Finish(); +</pre> +<h3 id="ConvertToUnicode()">ConvertToUnicode()</h3> +<p>Converts the data from one Charset to Unicode.</p> +<pre>AString ConvertToUnicode( + in ACString aSrc +); +</pre> +<h3 id="convertFromByteArray()">convertFromByteArray()</h3> +<p>Converts an array of bytes to a unicode string.</p> +<pre>AString convertFromByteArray( + [const,array,size_is(aCount)] in octet aData, + in unsigned long aCount +); +</pre> +<h3 id="convertToByteArray()">convertToByteArray()</h3> +<p>Convert a unicode string to an array of bytes. Finish does not need to be called.</p> +<pre>void convertToByteArray(in AString aString, + out unsigned long aLen, <span class="inlineIndicator optional optionalInline">可选</span> + [array, size_is(aLen),retval] out octet aData +); +</pre> +<h3 id="convertToInputStream()">convertToInputStream()</h3> +<p>Converts a Unicode string to an input stream. The bytes in the stream are encoded according to the <code>charset</code> attribute. The returned stream is non-blocking.</p> +<pre>nsIInputStream convertToInputStream( + in AString aString + ); +</pre> +<h6 id="Parameters">Parameters</h6> +<h6 id="Return_value">Return value</h6> +<p>An <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIInputStream" title="">nsIInputStream</a></code> that will present the text specified in <code>aString</code> as its data.</p> +<ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + <li> + <ul> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + <li> + <ul> + <li> + <dl> + <dt> + <code>aString</code></dt> + <dd> + The text to encode to the stream. The text is encoded into the character set specified by the <code>charset</code> attribute.</dd> + </dl> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> +</ul> +<dl> +</dl> +<h2 id="Examples" name="Examples">Examples</h2> +<p>See <a href="/zh-cn/Reading_textual_data" title="zh-cn/Reading_textual_data">Reading textual data</a> and <a href="/zh-cn/Writing_textual_data" title="zh-cn/Writing_textual_data">Writing textual data</a> for examples.</p> +<p></p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsisyncmessagesender/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsisyncmessagesender/index.html new file mode 100644 index 0000000000..1af1e116c3 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsisyncmessagesender/index.html @@ -0,0 +1,65 @@ +--- +title: nsISyncMessageSender +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsISyncMessageSender +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsISyncMessageSender +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/content/base/public/nsIMessageManager.idl" rel="custom">content/base/public/nsIMessageManager.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +Handles sending messages synchronously to a destination frame. +</span> + + <div style="height: 42px; position: relative; padding: 2px; width: auto;"> + + <div style="top: 22px; font-size: 11px; position: absolute;">1.0</div> + + <div style="top: 22px; font-size: 11px; position: absolute; left: 0px; text-align: right; float: right; width: 100%;">66</div> + + <div style="height: 8px; top: 16px; background: #dd0000; left: 0px; position: absolute; width: 11.428571428571429%;"></div> + +<div style="height: 8px; top: 16px; left: 11.428571428571429%; background: #00dd00; position: absolute; width: 88.57142857142857%;" title="Introduced in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)"></div> + +<div style="top: 0px; font-size: 11px; position: absolute; left: 11.428571428571429%;">Introduced</div> +<div style="top: 22px; font-size: 11px; position: absolute; left: 11.428571428571429%;">Gecko 2.0</div> + +</div> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFrameMessageManager" title="">nsIFrameMessageManager</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)</span></div> +</div><p></p> +<h2 id="Method_overview" name="Method_overview">方法概述</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>void sendSyncMessage(in messageName, in JSON, in [array] jsObjects);</code></td> + </tr> + </tbody> +</table> +<h3 id="sendSyncMessage()">sendSyncMessage()</h3> +<p>同步发送一条短消息.</p> +<pre>void sendSyncMessage( + in DOMString messageName, + in DOMString json, +); +</pre> +<h6 id="Parameters">Parameters</h6> +<dl> + <dt> + <code>messageName</code></dt> + <dd> + 消息的名称.</dd> + <dt> + <code>json</code></dt> + <dd> + 一个JSON格式的字符串,代表了要发送的数据.</dd> +</dl> +<h2 id="See_also" name="See_also">相关链接</h2> +<ul> + <li><a href="/en/Content_process_event_handling" title="en/Content process event handling">Content process event handling</a></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIChromeFrameMessageManager" title="">nsIChromeFrameMessageManager</a></code></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIContentFrameMessageManager" title="">nsIContentFrameMessageManager</a></code></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFrameLoader" title="">nsIFrameLoader</a></code></li> + <li><code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIFrameMessageListener" title="">nsIFrameMessageListener</a></code></li> +</ul> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsitimer/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsitimer/index.html new file mode 100644 index 0000000000..24cfb2eb4f --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsitimer/index.html @@ -0,0 +1,285 @@ +--- +title: nsITimer +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsITimer +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsITimer +--- +<div id="page-top"> + <div class="pageText" id="pageText"> + <p>nsITimer 接口的功能是：在指定延迟后唤醒一个程序。</p> + <p><span class="lang lang-en"><code>nsITimer</code> 的定义文档： <span class="lang lang-en"><a class="external" href="http://mxr.mozilla.org/mozilla-central/source/xpcom/threads/nsITimer.idl" rel="external nofollow" title="http://mxr.mozilla.org/mozilla-central/source/xpcom/threads/nsITimer.idl"><code>xpcom/threads/nsITimer.idl</code></a> </span>。It is <span class="lang lang-en"><a href="../../../../en/Interfaces/About_Scriptable_Interfaces" rel="internal">scriptable</a> </span> and <span class="lang lang-en"> <a href="../../../../en/Interfaces/About_Frozen_Interfaces" rel="internal">unfrozen</a> (hasn't changed since 1.9.1) </span>. </span></p> + <p>继承自： <span class="lang lang-en"><code><a href="../../../../en/nsISupports" rel="internal">nsISupports</a></code> </span></p> + <p>实现： <code>@mozilla.org/timer;1</code>。创建实例如：</p> + <pre class="eval">var timer = Components.classes["@mozilla.org/timer;1"] + .createInstance(Components.interfaces.nsITimer); +</pre> + <div id="section_1"> + <h2 class="editable" id="方法预览"><span>方法预览</span></h2> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" style="" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <table class="standard-table"> + <tbody> + <tr> + <td><code>void <a href="/../../../../En/NsITimer#initWithCallback.28.29" title="../../../../En/NsITimer#initWithCallback.28.29">initWithCallback</a>(in <span class="lang lang-en"><code><a href="../../../../en/nsITimerCallback" rel="internal">nsITimerCallback</a></code> </span> aCallback, in unsigned long aDelay, in unsigned long aType);</code></td> + </tr> + <tr> + <td><code>[noscript] void <a href="/../../../../En/NsITimer#initWithFuncCallback.28.29" title="../../../../En/NsITimer#initWithFuncCallback.28.29">initWithFuncCallback</a>(in <span class="lang lang-en"><code><a class="new" href="../../../../en/nsITimerCallbackFunc" rel="internal">nsITimerCallbackFunc</a></code> </span> aCallback, in voidPtr aClosure, in unsigned long aDelay, in unsigned long aType);</code></td> + </tr> + <tr> + <td><code>void <a href="/../../../../En/NsITimer#init.28.29" title="../../../../En/NsITimer#init.28.29">init</a>(in <span class="lang lang-en"><code><a href="../../../../en/nsIObserver" rel="internal">nsIObserver</a></code> </span> aObserver, in unsigned long aDelay, in unsigned long aType);</code></td> + </tr> + <tr> + <td><code>void <a href="/../../../../En/NsITimer#cancel.28.29" title="../../../../En/NsITimer#cancel.28.29">cancel</a>();</code></td> + </tr> + </tbody> + </table> + </div> + <div id="section_2"> + <h2 class="editable" id="属性"><span>属性</span></h2> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <table class="standard-table"> + <tbody> + <tr> + <td class="header">Attribute</td> + <td class="header">Type</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>delay</code></td> + <td><code>unsigned long</code></td> + <td>The timeout delay in millisecond.</td> + </tr> + <tr> + <td><code>type</code></td> + <td><code>unsigned long</code></td> + <td>Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under <span class="lang lang-en"><a href="/../../../../En/NsITimer#Constants" title="../../../../En/NsITimer#Constants">Constants</a> </span> on this page</td> + </tr> + <tr> + <td><code>callback</code></td> + <td><code>readonly <span class="lang lang-en"><code><a href="../../../../en/nsITimerCallback" rel="internal">nsITimerCallback</a></code> </span> </code></td> + <td>The <code>nsITimerCallback</code> object passed to <code>initWithCallback()</code>.</td> + </tr> + <tr> + <td><code>closure</code></td> + <td><code>[noscript] readonly voidPtr</code></td> + <td> + <p>The opaque pointer pass to <code>initWithFuncCallback()</code>.</p> + </td> + </tr> + <tr> + <td>target</td> + <td><span class="lang lang-en"><code><a class="new" href="../../../../en/nsIEventTarget" rel="internal">nsIEventTarget</a></code> </span></td> + <td>The <span class="lang lang-en"><code><a class="new" href="../../../../en/nsIEventTarget" rel="internal">nsIEventTarget</a></code> </span> to which the callback is dispatched. This target must be set before calling any of the initialization methods.</td> + </tr> + </tbody> + </table> + </div> + <div id="section_3"> + <h2 class="editable" id="常量"><span>常量</span></h2> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <table class="standard-table"> + <tbody> + <tr> + <td class="header">Constant</td> + <td class="header">Value</td> + <td class="header">Description</td> + </tr> + <tr> + <td><code>TYPE_ONE_SHOT</code></td> + <td>0</td> + <td>Type of a timer that fires once only.</td> + </tr> + <tr> + <td><code>TYPE_REPEATING_SLACK</code></td> + <td>1</td> + <td>After firing, the timer is stopped and not restarted until its callback completes. Specified timer period will be at least the time between when processing for last firing the callback completes and when the next firing occurs.</td> + </tr> + <tr> + <td><code>TYPE_REPEATING_PRECISE</code></td> + <td>2</td> + <td>This repeating timer aims to have constant period between firings. The processing time for each timer callback should not influence the timer period. However, if the processing for the last timer firing could not be completed until just before the next firing occurs, then you could have two timer notification routines being executed in quick succession.</td> + </tr> + </tbody> + </table> + </div> + <div id="section_4"> + <h2 class="editable" id="方法"><span>方法</span></h2> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <div id="section_5"> + <h3 class="editable" id="initWithCallback()"><span>initWithCallback()</span></h3> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p>Initialize a timer to fire after the given millisecond interval. This version takes a function to call and a closure to pass to that function.</p> + <pre class="eval"> void initWithCallback ( + in nsITimerCallback aCallback, + in unsigned long aDelay, + in unsigned long aType + ); +</pre> + <div id="section_6"> + <h6 class="editable" id="Parameters"><span>Parameters</span></h6> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <dl> + <dt> + <code>aFunc</code></dt> + <dd> + <span class="lang lang-en"><code><a href="../../../../en/nsITimerCallback" rel="internal">nsITimerCallback</a></code> </span> interface to call when timer expires.</dd> + </dl> + <dl> + <dt> + <code>aDelay</code></dt> + <dd> + timeout delay in milliseconds.</dd> + </dl> + <dl> + <dt> + <code>aType</code></dt> + <dd> + Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under <span class="lang lang-en"><a href="/../../../../En/NsITimer#Constants" title="../../../../En/NsITimer#Constants">Constants</a> </span> on this page.</dd> + </dl> + </div> + </div> + <div id="section_7"> + <h3 class="editable" id="initWithFuncCallback()"><span>initWithFuncCallback()</span></h3> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p>Initialize a timer to fire after the given millisecond interval. This version takes a function to call and a closure to pass to that function.</p> + <pre class="eval"> [noscript] void initWithFuncCallback( + in nsTimerCallbackFunc aCallback, + in voidPtr aClosure, + in unsigned long aDelay, + in unsigned long aType + ); +</pre> + <div id="section_8"> + <h6 class="editable" id="Parameters_2"><span>Parameters</span></h6> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <dl> + <dt> + <code>aFunc</code></dt> + <dd> + a <span class="lang lang-en"><code><a class="new" href="../../../../en/nsITimerCallbackFunc" rel="internal">nsITimerCallbackFunc</a></code> </span> interface compatible function to call when timer fires.</dd> + </dl> + <dl> + <dt> + <code>aClosure</code></dt> + <dd> + An opaque pointer to pass to that function.</dd> + </dl> + <dl> + <dt> + <code>aDelay</code></dt> + <dd> + timeout delay in milliseconds.</dd> + </dl> + <dl> + <dt> + <code>aType</code></dt> + <dd> + Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under <span class="lang lang-en"><a href="/../../../../En/NsITimer#Constants" title="../../../../En/NsITimer#Constants">Constants</a> </span> on this page.</dd> + </dl> + </div> + </div> + <div id="section_9"> + <h3 class="editable" id="init()"><span>init()</span></h3> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p>Initialize a timer that will fire after the specified delay. A user must keep a reference to this timer till it is no longer needed or has been canceled.</p> + <pre class="eval"> void init( + in nsIObserver aObserver, + in unsigned long aDelay, + in unsigned long aType + ); +</pre> + <div id="section_10"> + <h6 class="editable" id="Parameters_3"><span>Parameters</span></h6> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <dl> + <dt> + <code>aObserver</code></dt> + <dd> + A callback Object, that is capable listening to timer events. If the timer fires, the observer will be notified via the <span class="lang lang-en"><code><a href="../../../../en/nsIObserver" rel="internal">nsIObserver</a></code> </span> Interface. The subject is set to the <code>nsITimer</code> Object which fired, the topic is equal to "timer-callback" and data is always set to null.</dd> + </dl> + <dl> + <dt> + <code>aDelay</code></dt> + <dd> + timeout delay in milliseconds.</dd> + </dl> + <dl> + <dt> + <code>aType</code></dt> + <dd> + Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under <span class="lang lang-en"><a href="/../../../../En/NsITimer#Constants" title="../../../../En/NsITimer#Constants">Constants</a> </span> on this page.</dd> + </dl> + </div> + </div> + <div id="section_11"> + <h3 class="editable" id="cancel()"><span>cancel()</span></h3> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p>Cancels the timer. This method works on all types, not just on repeating timers -- you might want to cancel a TYPE_ONE_SHOT timer, and even reuse it by re-initializing it (to avoid object destruction and creation costs by conserving one timer instance).</p> + <pre class="eval"> void cancel(); +</pre> + <div id="section_12"> + <h6 class="editable" id="Parameters_4"><span>Parameters</span></h6> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p>None.</p> + </div> + </div> + </div> + <div id="section_13"> + <h2 class="editable" id="备注"><span>备注</span></h2> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" style="" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p>TYPE_REPEATING_SLACK timer is the preferable repeating timer type for most situations<span id="1243145776531S" style="display: none;"> </span></p> + </div> + <div id="section_14"> + <h2 class="editable" id="sect1"> </h2> + <div class="editIcon"> + 实例</div> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <pre class="eval"> // we need a <span class="lang lang-en"><code><a href="../../../../en/nsITimerCallback" rel="internal">nsITimerCallback</a></code> +</span> compatible... + // ... interface for the callbacks. + var event + = { notify: function(timer) { alert("Fire!"); } } + + // Now it is time to create the timer... + var timer + = Components.classes["@mozilla.org/timer;1"] + .createInstance(Components.interfaces.nsITimer); + + // ... and to initialize it, we want to call event.notify() ... + // ... one time after exactly ten second. + timer.initWithCallback( + event, + 10000, + Components.interfaces.nsITimer.TYPE_ONE_SHOT); +</pre> + <p> </p> + </div> + <div id="section_15"> + <h2 class="editable" id="请参阅"><span>请参阅</span></h2> + <div class="editIcon"> + <a href="/../../../../En/NsITimer#" title="Edit section"><span class="icon"><img alt="Edit section" class="sectionedit" src="../../../../skins/common/icons/icon-trans.gif"></span></a></div> + <p><span class="lang lang-en"><code><a class="new" href="../../../../en/nsITimerCallbackFunc" rel="internal">nsITimerCallbackFunc</a></code> </span>, <span class="lang lang-en"><code><a href="../../../../en/nsITimerCallback" rel="internal">nsITimerCallback</a></code></span></p> + </div> + </div> +</div> + +<p><strong class="tag-label">标记：</strong></p> +<div id="pageTags"> + <div class="pageTagList"> + <div class="item taglist"> + <a href="/../../../../Special:Tags?tag=Interfaces&language=en" title="Interfaces">Interfaces</a>, <a href="/../../../../Special:Tags?tag=Interfaces:Scriptable&language=en" title="Interfaces:Scriptable">Interfaces:Scriptable</a>, <a href="/../../../../Special:Tags?tag=XPCOM&language=en" title="XPCOM">XPCOM</a>, <a href="/../../../../Special:Tags?tag=XPCOM+API+Reference&language=en" title="XPCOM API Reference">XPCOM API Reference</a></div> + </div> +</div> +<p> </p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsitraceablechannel/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsitraceablechannel/index.html new file mode 100644 index 0000000000..ce7c6deb2f --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsitraceablechannel/index.html @@ -0,0 +1,71 @@ +--- +title: nsITraceableChannel +slug: Mozilla/Tech/XPCOM/Reference/Interface/NsITraceableChannel +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/NsITraceableChannel +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/netwerk/base/public/nsITraceableChannel.idl" rel="custom">netwerk/base/public/nsITraceableChannel.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;">这个接口用于允许拦截 <a href="/en-US/docs/HTTP" title="/en-US/docs/HTTP">HTTP</a> 流量。It is implemented by <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIHttpChannel" title="">nsIHttpChannel</a></code>.</span> + + <div style="height: 42px; position: relative; padding: 2px; width: auto;"> + + <div style="top: 22px; font-size: 11px; position: absolute;">1.0</div> + + <div style="top: 22px; font-size: 11px; position: absolute; left: 0px; text-align: right; float: right; width: 100%;">66</div> + + <div style="height: 8px; top: 16px; background: #dd0000; left: 0px; position: absolute; width: 8.952380571428572%;"></div> + +<div style="height: 8px; top: 16px; left: 8.952380571428572%; background: #00dd00; position: absolute; width: 91.04761942857142%;" title="Introduced in Gecko 1.9.0.4 "></div> + +<div style="top: 0px; font-size: 11px; position: absolute; left: 8.952380571428572%;">Introduced</div> +<div style="top: 22px; font-size: 11px; position: absolute; left: 8.952380571428572%;">Gecko 1.9.0.4</div> + +</div> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 1.9.0.4 </span></div> +</div><p></p> +<p>使用这个接口的典型方式如下：</p> +<ul> + <li><a href="/en/XUL_School/Intercepting_Page_Loads#HTTP_Observers" title="en/XUL_School/Intercepting_Page_Loads#HTTP_Observers">注册“http-on-examine-response”通知</a>来跟综全部 HTTP 响应；</li> + <li>跳过重定义 (<code>responseStatus</code> = 3xx on <a href="/en-US/docs/XPCOM_Interface_Reference/nsIHttpChannel" title="/en-US/docs/XPCOM_Interface_Reference/nsIHttpChannel">nsIHttpChannel</a>)，否则你可能<a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=728901#c8" title="https://bugzilla.mozilla.org/show_bug.cgi?id=728901#c8">最终有两个监听视（listeners）注册通道（channel）</a>;</li> + <li>QI the channel passed as the "<code>subject</code>" to your observer to <code>nsITraceableChannel</code>, and replace the default <code>nsIStreamListener</code> (that passes the data to the original requester - e.g. to XMLHttpRequest or to the browser tab that made the request) with your own implementation (see <a href="#Using_channel_listeners" title="#Using_channel_listeners">"Implementing nsIStreamListener"</a> below).</li> +</ul> +<p>之后，你的 nsIStreamListener 实现将会获取到响应数据（response data），并且能够传递数据到原始的 nsIStreamListener（可能会修改它）。</p> +<p>See <a class="external" href="http://www.softwareishard.com/blog/firebug/nsitraceablechannel-intercept-http-traffic/" title="http://www.softwareishard.com/blog/firebug/nsitraceablechannel-intercept-http-traffic/">nsITraceableChannel, Intercept HTTP Traffic</a> for a more detailed description with code samples.</p> +<p>See <a href="http://stackoverflow.com/questions/5205672/modify-url-before-loading-page-in-firefox/" title="http://stackoverflow.com/questions/5205672/modify-url-before-loading-page-in-firefox/"> Modify URL before loading page in firefox</a> for an overview of how to <strong>modify</strong> a request before it is made.</p> +<h2 id="Method_overview" name="Method_overview">Method overview</h2> +<table class="standard-table"> + <tbody> + <tr> + <td><code>nsIStreamListener <a href="#setNewListener()">setNewListener</a>(in nsIStreamListener aListener);</code></td> + </tr> + </tbody> +</table> +<h2 id="Methods" name="Methods">Methods</h2> +<h3 id="setNewListener()" name="setNewListener()">setNewListener()</h3> +<p>用一个新的来替换该通道的当前监听器，返回先前分配给该通道的监听器。</p> +<pre class="eval">nsIStreamListener setNewListener( + in nsIStreamListener aListener +); +</pre> +<h6 id="Parameters" name="Parameters">参数</h6> +<dl> + <dt> + <code>aListener</code></dt> + <dd> + An <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIStreamListener" title="">nsIStreamListener</a></code> to be notified of events on the HTTP channel.</dd> +</dl> +<h6 id="Return_value" name="Return_value">返回值</h6> +<p>该通道的前一个监听器。Each listener call through to the previous listener for every call, in order to establish a call chain to allow all interested parties a chance to act on each event.</p> +<h2 id="Using_channel_listeners" name="Using_channel_listeners">实现 nsIStreamListener</h2> +<p>一个 <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIStreamListener" title="">nsIStreamListener</a></code> 接口传递给 <code>setNewListener()</code> 需要实现下列的方法，这是通过调用（这些方法）来通知它在 HTTP stream 上发生的事件：</p> +<ul> + <li><code>onStartRequest</code>：一个 HTTP 请求开始。</li> + <li><code>onDataAvailable：</code>数据到达 HTTP 通道（HTTP channel）。</li> + <li><code>onStopRequest</code>：HTTP 请求结束。</li> +</ul> +<div class="note"> + <strong>Note:</strong> It is critical that you pass along requests to the previous listener as soon as possible -- especially for <code>onStartRequest</code>.</div> +<p>Channels may restrict when you may replace the listener. In particular, listeners typically should not be replaced after <code>onStartRequest</code> has been called.</p> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiuri/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiuri/index.html new file mode 100644 index 0000000000..d133861ac3 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsiuri/index.html @@ -0,0 +1,407 @@ +--- +title: nsIURI +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIURI +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIURI +--- +<p></p><div style="border: solid #ddd 2px; margin-bottom: 12px;"> +<div style="background: #eee; padding: 2px;"><code><a href="https://dxr.mozilla.org/mozilla-central/source/netwerk/base/public/nsIURI.idl" rel="custom">netwerk/base/public/nsIURI.idl</a></code><span style="text-align: right; float: right;"><a href="/zh-CN/docs/Interfaces/About_Scriptable_Interfaces" style="color: #00cc00; font-weight: 700;">脚本化</a></span></div> +<span style="padding: 4px 2px;"> + +这是具有国际化支持的统一资源标识符的接口，提供允许设置和查询URI基本组件的属性以及用于在URI上执行基本操作的方法。 +</span> + +<div style="background: #eee; padding: 2px;"> +继承于: <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsISupports" title="">nsISupports</a></code> +<span style="text-align: right; float: right;">最后修改于Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)</span></div> +</div><p></p> + +<p>细节请查看下列 RFCs:</p> + +<ul> + <li><a class="external" href="http://www.ietf.org/rfc/rfc3490.txt" title="http://www.ietf.org/rfc/rfc3490.txt">RFC3490</a>: 在应用程序中的国际域名 (IDNA)</li> + <li><a class="external" href="http://tools.ietf.org/rfc/rfc3986.txt" title="http://tools.ietf.org/rfc/rfc3986.txt">RFC3986</a>: 统一资源标识符 (URI): 通用词法</li> + <li><a class="external" href="http://tools.ietf.org/rfc/rfc3987.txt" title="http://tools.ietf.org/rfc/rfc3987.txt">RFC3987</a>: 国际化的内容标识</li> +</ul> + +<p><code>nsIURI</code>的子类, 例如 <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIURL" title="">nsIURL</a></code>, 加强了URI未来的结构化.</p> + +<p>为了创建一个 <code>nsIURI</code> 对象, 你应该如此使用 <code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIIOService#newURI()">nsIIOService.newURI()</a></code>:</p> + +<pre class="brush: js">function makeURI(aURL, aOriginCharset, aBaseURI) { + var ioService = Components.classes["@mozilla.org/network/io-service;1"] + .getService(Components.interfaces.nsIIOService); + return ioService.newURI(aURL, aOriginCharset, aBaseURI); +} +</pre> + +<h2 id="Components_of_a_URI" name="Components_of_a_URI">一个 URI 的组件</h2> + +<table class="standard-table"> + <thead> + <tr> + <th colspan="7" scope="col" style="text-align: center;">prePath</th> + <th colspan="2" scope="col" style="text-align: center;">path</th> + </tr> + <tr> + <th scope="col" style="text-align: center;">scheme</th> + <th scope="col" style="text-align: center;"> </th> + <th scope="col" style="text-align: center;">userPass</th> + <th scope="col" style="text-align: center;"> </th> + <th scope="col" style="text-align: center;">host</th> + <th scope="col" style="text-align: center;"> </th> + <th scope="col" style="text-align: center;">port</th> + <th scope="col" style="text-align: center;"> </th> + <th scope="col" style="text-align: center;">ref</th> + </tr> + </thead> + <tbody> + <tr> + <td style="text-align: right;">ftp</td> + <td>://</td> + <td>username@password</td> + <td>@</td> + <td>hostname</td> + <td>:</td> + <td>portnumber</td> + <td>/pathname?query=value</td> + <td>#ref</td> + </tr> + </tbody> +</table> + +<h2 id="Method_overview" name="Method_overview">函数预览</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td><code>nsIURI <a href="#clone()">clone</a>();</code></td> + </tr> + <tr> + <td><code>nsIURI <a href="#cloneIgnoringRef()">cloneIgnoringRef</a>();</code> </td> + </tr> + <tr> + <td><code>boolean <a href="#equals()">equals</a>(in nsIURI other);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#equalsExceptRef()">equalsExceptRef</a>(in nsIURI other);</code> </td> + </tr> + <tr> + <td><code>AUTF8String <a href="#resolve()">resolve</a>(in AUTF8String relativePath);</code></td> + </tr> + <tr> + <td><code>boolean <a href="#schemeIs()">schemeIs</a>(in string scheme);</code></td> + </tr> + </tbody> +</table> + +<h2 id="Attributes" name="Attributes">属性</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">属性</td> + <td class="header">类别</td> + <td class="header">描述</td> + </tr> + <tr> + <td><code>asciiHost</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a></code></td> + <td> + <p>The URI <code>host</code> with an ASCII compatible encoding. Follows the IDNA draft specification for converting internationalized domain names (UTF-8) to ASCII for compatibility with existing Internet infrastructure. <strong>Read only.</strong></p> + + <div class="note"> + <p><strong>Note:</strong> IPv6 addresses are not enclosed in square brackets.</p> + </div> + </td> + </tr> + <tr> + <td><code>asciiSpec</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a> (US-ASCII)</code></td> + <td>The URI spec with an ASCII compatible encoding. The host portion follows the IDNA draft spec. Other parts are URL-escaped per the rules of <a class="external" href="http://tools.ietf.org/rfc/rfc3986.txt" title="http://tools.ietf.org/rfc/rfc3986.txt">RFC3986</a>. The result is strictly ASCII. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>hasRef</code></td> + <td><code>boolean</code></td> + <td>Returns if there is a reference portion (the part after the "#") of the URI.<br> + <br> + </td> + </tr> + <tr> + <td><code>host</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The host is the Internet domain name to which this URI refers. It could be an IPv4 (or IPv6) address literal. If supported, it could be a non-ASCII internationalized domain name.</p> + + <h6 id="Exceptions_thrown">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If host is not applicable to the URI scheme (e.g. about:blank)</dd> + </dl> + + <div class="note"><strong>Note:</strong> Characters are <strong>not</strong> escaped. IPv6 addresses are not enclosed in square brackets.</div> + </td> + </tr> + <tr> + <td><code>hostPort</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The "host:port" part of the URI (or simply the host, if port is -1).</p> + + <h6 id="Exceptions_thrown_2">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If hostPort is not applicable to the URI scheme (e.g. about:blank)</dd> + </dl> + + <div class="note"><strong>Note:</strong> Characters are <strong>not</strong> escaped.</div> + </td> + </tr> + <tr> + <td><code>originCharset</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a></code></td> + <td> + <p>The charset of the document from which this URI originated. An empty value implies UTF-8.</p> + If this value is something other than UTF-8 then the URI components (for example <code>spec</code>, <code>prePath</code>, <code>username</code>, and so on) are all fully URL-escaped. Otherwise, the URI components may contain unescaped multibyte UTF-8 characters. <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>password</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The optional password, assuming the <code>preHost</code> consists of "username:password".</p> + + <h6 id="Exceptions_thrown_3">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If password is not applicable to the URI scheme (e.g. about:blank)</dd> + </dl> + + <p></p><div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div><p></p> + </td> + </tr> + <tr> + <td><code>path</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The path, typically including at least a leading '/' (but may also be empty, depending on the protocol).</p> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div></td> + </tr> + <tr> + <td><code>port</code></td> + <td><code><a href="/en/long" title="en/long">long</a></code></td> + <td> + <p>The URI's port. A port value of -1 corresponds to the protocol's default port (for example -1 implies port 80 for HTTP URIs).</p> + + <h6 id="Exceptions_thrown_4">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If port is not applicable to the URI scheme (e.g. about:blank)</dd> + </dl> + </td> + </tr> + <tr> + <td><code>prePath</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The <code>prePath</code> returns the string before the path (such as "<a class="external" rel="freelink">scheme://user:password@host</a>:port").</p> + + <p>This is related to the <a class="external" href="http://tools.ietf.org/html/rfc6454" title="http://tools.ietf.org/html/rfc6454">Web Origin Concept of RFC6454</a>.</p> + + <p>This is useful for authentication, managing sessions, or for checking the <code>origin</code> of an URI to prevent cross-site scripting attacks while using methods such as <a href="/zh-CN/docs/Web/API/Window/postMessage" title="window.postMessage() 方法可以安全地实现跨源通信。通常，对于两个不同页面的脚本，只有当执行它们的页面位于具有相同的协议（通常为https），端口号（443为https的默认值），以及主机 (两个页面的模数 Document.domain设置为相同的值) 时，这两个脚本才能相互通信。window.postMessage() 方法提供了一种受控机制来规避此限制，只要正确的使用，这种方法就很安全。"><code>window.postMessage()</code></a>.</p> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div> <strong>Read only.</strong></td> + </tr> + <tr> + <td><code>ref</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>Returns the reference portion (the part after the "#") of the URI. If there is not one, an empty string is returned.</p> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div> </td> + </tr> + <tr> + <td><code>scheme</code></td> + <td><code><a href="/en/ACString" title="en/ACString">ACString</a> (US-ASCII)</code></td> + <td> + <p>The <code>scheme</code> is the protocol to which this URI refers. The scheme is restricted to the US-ASCII charset per <a class="external" href="http://tools.ietf.org/rfc/rfc3986.txt" title="http://tools.ietf.org/rfc/rfc3986.txt">RFC3986</a>.</p> + + <div class="warning"><strong>Warning:</strong> Setting this is highly discouraged outside of a protocol handler implementation, since doing so will generally lead to unpredictable results.</div> + </td> + </tr> + <tr> + <td><code>spec</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>Returns a string representation of the URI. Setting the <code>spec</code> causes the new spec to be parsed using the rules for the scheme the URI currently has. If the string cannot be parsed as a URI, <code>NS_ERROR_MALFORMED_URI</code> thrown.</p> + + <div class="warning"><strong>Warning:</strong> Because parsing the string is done using the current URI's scheme, setting the spec to a URI with a different scheme will produce incorrect results. Therefore, only protocol handler implementations should do this.</div> + + <p>If the URI stores information from the <code><a href="/zh-CN/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIIOService" title="">nsIIOService</a></code> interface's <code><a href="https://developer.mozilla.org/zh-CN/docs/XPCOM_Interface_Reference/nsIIOService#newURI()">nsIIOService.newURI()</a></code> call that created it, other than just the parsed string, the behavior of this information when setting the <code>spec</code> attribute is undefined.</p> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div></td> + </tr> + <tr> + <td><code>specIgnoringRef</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td>Returns a string representation of the URI without the <code>ref</code> (part after the #) portion.<br> + <br> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div> </td> + </tr> + <tr> + <td><code>username</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The optional username, assuming the <code>preHost</code> consists of "username:password".</p> + + <h6 id="Exceptions_thrown_5">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If username is not applicable to the URI scheme (e.g. about:blank)</dd> + </dl> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div></td> + </tr> + <tr> + <td><code>userPass</code></td> + <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> + <td> + <p>The "username:password" (or username only if the value doesn't contain a ':').</p> + + <h6 id="Exceptions_thrown_6">Exceptions thrown</h6> + + <dl> + <dt><code>NS_ERROR_FAILURE</code></dt> + <dd>If userPass is not applicable to the URI scheme (e.g. about:blank)</dd> + </dl> + <div class="blockIndicator note"><strong>Note:</strong> Some characters may be escaped.</div></td> + </tr> + </tbody> +</table> + +<h2 id="Methods" name="Methods">Methods</h2> + +<h3 id="clone()" name="clone()">clone()</h3> + +<p>Clones the URI, returning a new <code>nsIURI</code> object.</p> + +<div class="note"><strong>Note:</strong> For some protocols, this is more than just an optimization. For example, under Mac OS X, the spec of a file URI doesn't necessarily uniquely identify a file, since two volumes can have the same name.</div> + +<pre class="eval">nsIURI clone(); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<p>None.</p> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>An <code>nsIURI</code> object that represents the same URI as the current <code>nsIURI</code>.</p> + +<p></p><h3 id="cloneIgnoringRef()">cloneIgnoringRef()</h3><p></p> + +<p>Clones the current URI, clearing the <code>'ref'</code> attribute in the clone.</p> + +<pre class="eval">nsIURI cloneIgnoringRef(); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<p>None.</p> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>An <code>nsIURI</code> object that represents the same URI as the current <code>nsIURI</code> without the <code>'ref'</code> attribute.</p> + +<h3 id="equals()" name="equals()">equals()</h3> + +<p>Compares the current URI with another URI.</p> + +<div class="note"><strong>Note:</strong> This is more than a string comparison, as two different URI strings can represent the same location. For example, comparing "<a class="external" href="http://foo.com:80/" rel="freelink">http://foo.com:80/</a>" and "<a class="external" href="http://foo.com/" rel="freelink">http://foo.com/</a>" will return <code>true</code>.</div> + +<pre class="eval">boolean equals( + in nsIURI other +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>other</code></dt> + <dd>Another <code>nsIURI</code> to compare to.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p><code>true</code> if the two URIs represent the same location; otherwise <code>false</code>.</p> + +<p></p><h3 id="equalsExceptRef()">equalsExceptRef()</h3><p></p> + +<p>Compares the current URI with another URI, ignoring the value of the <code>.ref</code> member.</p> + +<div class="note"><strong>Note:</strong> This is more than a string comparison, as two different URI strings can represent the same location. For example, comparing "<a class="external" href="http://foo.com/#" rel="freelink">http://foo.com/#</a>" and "<a class="external" href="http://foo.com/" rel="freelink">http://foo.com/</a>" or "<a class="external" href="http://foo.com/#aaa" rel="freelink">http://foo.com/#aaa</a>" and "<a class="external" href="http://foo.com/#bbb" rel="freelink">http://foo.com/#bbb</a>" will return <code>true</code>.</div> + +<pre class="eval">boolean equalsExceptRef( + in nsIURI other +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>other</code></dt> + <dd>Another <code>nsIURI</code> to compare to.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p><code>true</code> if the two URIs represent the same location; otherwise <code>false</code>.</p> + +<h3 id="resolve()" name="resolve()">resolve()</h3> + +<p>Resolves a relative URI string, using this URI as the base.</p> + +<p></p><div class="blockIndicator note"><strong>Note:</strong> Some implementations may have no concept of a relative URI.</div><p></p> + +<pre class="eval">AUTF8String resolve( + in AUTF8String relativePath +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>relativePath</code></dt> + <dd>The relative path to resolve.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p>The resolved absolute URI string.</p> + +<h3 id="schemeIs()" name="schemeIs()">schemeIs()</h3> + +<p>Quickly reports whether the <code>nsIURI</code> represents a URI with the specified scheme. This comparison is case-insensitive.</p> + +<p></p><div class="blockIndicator note"><strong>Note:</strong> This is an optimization, allowing you to check the scheme of the URI without having to get the scheme and do the comparison yourself; this saves memory allocations.</div><p></p> + +<pre class="eval">boolean schemeIs( + in string scheme +); +</pre> + +<h6 id="Parameters" name="Parameters">Parameters</h6> + +<dl> + <dt><code>scheme</code></dt> + <dd>A string representing the scheme to compare to.</dd> +</dl> + +<h6 id="Return_value" name="Return_value">Return value</h6> + +<p><code>true</code> if the URI is for the specified scheme; otherwise <code>false</code>.</p> + +<h2 id="See_also" name="See_also">See also</h2> + +<ul> + <li><a href="/en/Code_snippets/URI_parsing" title="en/Code_snippets/URI_parsing">Code snippets:URI parsing</a></li> +</ul> diff --git a/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsixmlhttprequest/index.html b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsixmlhttprequest/index.html new file mode 100644 index 0000000000..f12f52cb12 --- /dev/null +++ b/files/zh-cn/mozilla/tech/xpcom/reference/interface/nsixmlhttprequest/index.html @@ -0,0 +1,90 @@ +--- +title: nsIXMLHttpRequest +slug: Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest +tags: + - XMLHttpRequest + - XPCOM API 参考 + - XPCOM 接口参考 + - 指南 + - 接口 +translation_of: Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequest +--- +<div class="blockIndicator obsolete obsoleteHeader"><p><strong><span class="icon-only-inline" title="This is an obsolete API and is no longer guaranteed to work."><i class="icon-trash"> </i></span> Obsolete since Gecko 60 (Firefox 60 / Thunderbird 60 / SeaMonkey 2.57)</strong><br>This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.</p></div> + +<p><code>nsIXMLHttpRequest</code> along with <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIJSXMLHttpRequest" title="">nsIJSXMLHttpRequest</a></code> and <code><a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIXMLHttpRequestEventTarget" title="">nsIXMLHttpRequestEventTarget</a></code> are Mozilla's implementation details of the DOM <a href="/en/DOM/XMLHttpRequest" title="en/DOM/XMLHttpRequest">XMLHttpRequest</a> object.</p> + +<div class="note"><strong>注意:</strong> 如果你是 Web 开发者或者 Mozilla add-on 开发者，请参考 <a href="/en/DOM/XMLHttpRequest">XMLHttpRequest</a>。</div> + +<p>This page contains documentation, specific to Mozilla application and add-on developers.</p> + +<p>The interface definition: <a href="https://dxr.mozilla.org/mozilla-central/source/dom/xhr/nsIXMLHttpRequest.idl">https://dxr.mozilla.org/mozilla-central/source/dom/xhr/nsIXMLHttpRequest.idl</a></p> + +<h3 id="Elevated_Privileges">Elevated Privileges</h3> + +<p>As mentioned in the "Non-Standard Properties" the property of <code>channel</code> was read-only. When using the XPCOM interface, as seen below in <a href="#Example_code">Example 2</a>, we can get access to this. The most obvious benefit is that we can set <a href="/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/NsIRequest#Constants">nsiRequest - Constants</a> in the <code>xhr.channel.loadFlags</code>. For instance, as done in <a href="#Example_code">Example 2</a>, the flag of <code>LOAD_ANONYMOUS</code> is added, this strips all user data (cookies, tokens, etc).</p> + +<h3 id="Using_event_handlers_from_native_code">Using event handlers from native code</h3> + +<p>(Not sure if it's up-to-date)</p> + +<p>From native code, the way to set up onload and onerror handlers is a bit different. Here is a comment from Johnny Stenback <<a class="link-mailto" href="mailto:jst@netscape.com" rel="freelink">jst@netscape.com</a>>:</p> + +<blockquote>The mozilla implementation of nsIXMLHttpRequest implements the interface nsIDOMEventTarget and that's how you're supported to add event listeners. Try something like this: nsCOMPtr<nsIDOMEventTarget> target(do_QueryInterface(myxmlhttpreq)); target->AddEventListener(NS_LITERAL_STRING("load"), mylistener, PR_FALSE) where mylistener is your event listener object that implements the interface nsIDOMEventListener. The 'onload', 'onerror', and 'onreadystatechange' attributes moved to nsIJSXMLHttpRequest, but if you're coding in C++ you should avoid using those.</blockquote> + +<p>Though actually, if you use addEventListener from C++ weird things will happen too, since the result will depend on what JS happens to be on the stack when you do it....</p> + +<p>Conclusion: Do not use event listeners on XMLHttpRequest from C++, unless you're aware of all the security implications. And then think twice about it.</p> + +<h2 id="Example_code" name="Example_code">Example code</h2> + +<p>This is a simple example code for opening a simple HTTP request from a xul application (like a Mozilla extension) without using observers:</p> + +<pre class="eval"> var req = Components.classes["@mozilla.org/xmlextras/xmlhttprequest;1"].createInstance(); + req.open('POST', "<a class="external" href="http://www.foo.bar:8080/nietzsche.do" rel="freelink">http://www.foo.bar:8080/nietzsche.do</a>", true); + req.send('your=data&and=more&stuff=here'); +</pre> + +<h2 id="Example_code" name="Example_code">Example 2</h2> + +<pre><code>var {Cu: utils, Cc: classes, Ci: instances} = Components; +Cu.import('resource://gre/modules/Services.jsm'); +function xhr(url, cb) { + let xhr = Cc["@mozilla.org/xmlextras/xmlhttprequest;1"].createInstance(Ci.nsIXMLHttpRequest); + + let handler = ev => { + evf(m => xhr.removeEventListener(m, handler, !1)); + switch (ev.type) { + case 'load': + if (xhr.status == 200) { + cb(xhr.response); + break; + } + default: + Services.prompt.alert(null, 'XHR Error', 'Error Fetching Package: ' + xhr.statusText + ' [' + ev.type + ':' + xhr.status + ']'); + break; + } + }; + + let evf = f => ['load', 'error', 'abort'].forEach(f); + evf(m => xhr.addEventListener(m, handler, false)); + + xhr.mozBackgroundRequest = true; + xhr.open('GET', url, true); + xhr.channel.loadFlags |= Ci.nsIRequest.LOAD_ANONYMOUS | Ci.nsIRequest.LOAD_BYPASS_CACHE | Ci.nsIRequest.INHIBIT_PERSISTENT_CACHING; + xhr.responseType = "arraybuffer"; //dont set it, so it returns string, you dont want arraybuffer. you only want this if your url is to a zip file or some file you want to download and make a nsIArrayBufferInputStream out of it or something + xhr.send(null); +} + +xhr('https://www.gravatar.com/avatar/eb9895ade1bd6627e054429d1e18b576?s=24&d=identicon&r=PG&f=1', data => { + Services.prompt.alert(null, 'XHR Success', data); + var file = OS.Path.join(OS.Constants.Path.desktopDir, "test.png"); + var promised = OS.File.writeAtomic(file, new UInt8Array(data)); + promised.then( + function() { + alert('succesfully saved image to desktop') + }, + function(ex) { + alert('FAILED in saving image to desktop') + } + ); +});</code></pre> |