Mozilla DOM Hacking Guide: Introduction to XPCOM11

今日胃カメラを飲んだ。
モニタに映った自分の胃壁を見るのはなかなか面白い。カメラを飲むのは苦痛であるが、ドクターが”今食道を下っている”とか”これから胃に入る”とか解説をしてくれるので、ふむふむという感じでモニタを見つめていた。しわしわの胃の内部が、普段見慣れない奇妙な生命の形としてそこに写し出されていた。

”胃炎で胃の中がボヤっとしているが、大きな問題はない。”との診断。喜んでいいのか悲しむべきか。fatal な状態でないのでとりあえずやれやれ。胃薬をもらった。

夜テレビで、剣を飲む男が出ていた。中国人の男が、天を仰ぎながら腸まで達しそうな長さの剣を口から飲み込んでいた。”健康診断のため胃カメラを飲みなさい”とつぶやいた。 (^^;

-----------------------------------------------

原文：　 青色表示
訳文：　 黒色表示
注記/訂正： 赤色表示

E. Tutorial : How to add a new interface
E.a. Introduction

E. Tutorial : 新しいインターフェイスの追加方法
E.a. 始めに

The purpose of this tutorial is to describe the process of adding a new interface to the DOM and then implementing it. A good understanding of the previous sections is preferred to understand this tutorial. You could want to add a new interface for several reasons, like the addition of a new DOM object, or to respect an eventual "Interface freeze". First we will take a look at XPIDL and how it can help you define interfaces. Next we will describe the build system, makefiles, etc... And finally, we will look at the implementation of our new interface through the creation of an nsIDOMFabian interface (Fabian is my first name ;-).

このチュートリアルの目的は、DOM に新しいインターフェイスを追加しそれを実装する方法を解説することです。チュートリアルを理解するために前節をよく理解することが推奨されます。新しいインターフェイスを追加したくなるのにはいくつかの理由があります。新しい DOM のオブジェクトを追加したり、最終的な”インターフェイスの凍結”を順守するためです。最初に XPIDL を調べて、それがどのようにインターフェイスの定義を支援可能か見てみましょう。次にビルドシステム、makefiles、などを解説します。最後に、nsIDOMFabian インターフェイス（Fabian は私の名前なのですが ;-)を通じてこれらの^*1新しいインターフェイスの実装を観てみましょう。

^*1→our new interface を”私たちの新しいインターフェイス”と直訳せずに”これらの・・・・”としました。なぜ"our"を使うのでしょうか？"our"とは writer と reders を言っているのでしょうか？、それともおそらく　Mozilla community （=Mozillaを支援する有志の集まり)を指しているのでしょう。とすれば、この場合直訳も可能かもしれません。次の段落にもこの"our" が出てきます

E.b. XPIDL

XPIDL stands for Cross-Platform Interface Definition Language. Instead of coding interfaces directly in C++, one can use XPIDL. It simplifies greatly the task of defining interfaces, and offers some interesting features, like automatic generation of documentation, and XPT generation. The first thing to do is to decide what our interface, nsIDOMFabian, will do. For the purpose of this document, I have chosen to implement a new HTML interface called nsIDOMFabian. It will be implemented by the class nsHTMLDocument.

XPIDL は Cross-Platform Interface Definition Language の頭文字です。 C++ でインターフェイスを直接コーディングせずに、 XPIDL を使うことが可能です。それを使用するとインターフェイスの定義のタスクを簡略化し、文書の自動生成や XPT の生成などの面白い機能をいくつか提供します。最初にするべきことは、私たちのインターフェイスである nsIDOMFabian　が何をするか決めます。この文書のために、私は nsIDOMFabian という新しい HTML インターフェイスを実装することを選択しました。そのインターフェイスは nsHTMLDocument クラスによって実装されます。

この後、コーディングのサンプルが延々と続きます。長くなるので、ここで切って続きは次回にしましょう。
See you tomorrow! (^-^)/~~~~

Mozilla DOM Hacking Guide: Introduction to XPCOM10

人気のない仕事部屋。ウウーツ、寒い。パソコンのドライブのパネルが冷たいよ。”冬将軍、やはりあなたは強かった！”(・_・、

----------------------------------------

原文：　 青色表示
訳文：　 黒色表示
注記/訂正： 赤色表示

At the beginning of this section, I talked about a second solution to get a pointer to an interface. This should be used in the case a getter function is not available. As you probably know, the "this" member of an object is a pointer to that object. You can thus simply cast "this" statically to the desired interface. You should however be absolutely sure of what you are doing before coding such a cast. It can lead to troubles with refcounting.

この節の始めに、インターフェイスへのポインタを取得する 2 つ目の方法について話しました。これは、getter 関数が有効でない場合に使われるはずです。おそらくご存知でしょうが、オブジェクトの”this”メンバはそのオブジェクトへのポインタです。そこで必要なインターフェイスへ static に”this”を単にキャストできます。しかしキャストする前にご自分の処理が絶対間違いようにしてください。間違いがあれば参照カウントで問題が発生します。

Here is a simple problem I encountered recently: In a member function of the nsHTMLAnchorElement class, I had to get a pointer to the nsIContent interface implemented by the nsHTMLAnchorElement object. However there is no such getter. I had to use the second solution:

nsCOMPtr content = getter_AddRefs(NS_STATIC_CAST(nsIContent*, this));
// Or, if you want to do the refcounting yourself,
nsIContent *content = NS_STATIC_CAST(nsIContent*, this);

最近遭遇した問題の例を紹介します: nsHTMLAnchorElement クラスのメンバ関数で、nsHTMLAnchorElement オブジェクトによって実装された nsIContent インターフェイスへのポインタを取得する必要がありました。しかし、getter 関数がなかったので 2 つ目の方法を使わなければなりませんでした:

nsCOMPtr content = getter_AddRefs(NS_STATIC_CAST(nsIContent*, this));
// または自分自身をカウントしたいならば、
nsIContent *content = NS_STATIC_CAST(nsIContent*, this);


The second form should be used with care, and is recommended only for advanced XPCOM'ers.

この 2 つめの構文は注意して扱われる必要があり、XPCOM プログラマーの上級者だけに推奨されます。


The use of XPCOM and nsCOMPtr's described until now covers about 80% of what you need to know to read the code, and even write some. I could go on about do_GetService, explain the implementation of QueryInterface, etc, but I feel this is not worth the trouble. For the more advanced topics of XPCOM, please see the XPCOM project page.

ここまでに解説しました XPCOM と nsCOMPtr の使用方法はコードを読んだり少しでも書くのに必要な知識の 80% をカバーしています。引き続き do_GetService へ進んで、QueryInterface などの実装を説明できますが、そこまでする必要があると思いません。そこで XPCOM のさらに詳しい内容については XPCOM プロジェクト頁を参照してください。


The next section is a tutorial on how to add a new interface to the Mozilla DOM, with build instructions et al, and the last section is a discussion of the more advanced topics of object-oriented C++, interface inheritance, and other fun stuff.

次の節は Mozilla DOM へ新しいインターフェイスを追加する方法に関するチュートリアルであり、ビルドの解説やその他を含みます。最後の節はオブジェクト指向の C++ 、インターフェイスの継承、その他面白いトピックに関する詳細の内容についての議論になっています。

これでとてもとても長かった QueryInterface() の節を終わります。
See you at the next section.(^Q^)/"

Mozilla DOM Hacking Guide: Introduction to XPCOM 9

昨日の続きをする。

原文：　 青色表示
訳文：　 黒色表示
注記/訂正： 赤色表示

NS_GET_IID is a macro that evaluates to the IID of the argument. It is a convenient way of comparing two interfaces for equality. We have already seen what getter_AddRefs() does to nsCOMPtr's. In this case we pass the address of the ifooptr2 pointer. Since nsFoo implements nsIFoo2, ifooptr2 will be assigned the address of the current instance of nsFoo. We can now call the methods defined on nsIFoo2 through ifooptr2:
　ifooptr2->FunctionOfnsIFoo2();

NS_GET_IID は引数の IID に対して評価をするマクロです。2 つのインターフェイスを比較して同一性を調べるのに便利です。nsCOMPtr への getter_AddRefs() の働きについてはすでに見たとおりです。今回は、ifooptr2 のアドレスを渡します。nsFoo は nsIFoo2 を実装するので、ifooptr2 は nsFoo の現在のインスタンスのアドレスを代入されます。すると、ifooptr2 経由で nsIFoo2 で定義されたメソッドを呼び出せます:
　ifooptr2->FunctionOfnsIFoo2();

If we now try to QueryInterface to an interface that is not implemented by nsFoo, the pointer passed in will be null. This is why, unless you are really really really sure of what you are doing, you should always check for the null-ness of the nsCOMPtr. The following example demonstrates this.
　 nsCOMPtr iptr(do_QueryInterface(ifooptr));
if(!iptr) {
// nsFoo doesn't implement nsINotImplemented. iptr is thus null.
return NS_OK;
}


nsFoo で実装されないインターフェイスへ QueryInterface を今試みるならば、渡されたポインタは null となります。そんな訳で、自分の処理を本当に確実に明白に間違いないと思われないなら、nsCOMPtr が　null になっていないかどうか必ず確認してください。以下のサンプルを参考にしてください。
　 nsCOMPtr iptr(do_QueryInterface(ifooptr));
if(!iptr) {
// nsFoo は nsINotImplemented を実装しない。 iptr はそのため null である。
return NS_OK;
}


It is also worth noting that QueryInterface is null-safe. For example, in the previous example, nothing bad will happen if ifooptr is null. Additionally, the return value of a call to QueryInterface should not be returned unless there is a good reason for that. If you are concerned that it could return NS_NOINTERFACE, return NS_OK, as the previous example shows.

QueryInterface が null-safe であることに注意することも大切です。たとえば前の例では、ifooptr がnull であっても、不都合は発生しません。さらに、QueryInterface への呼び出しの戻り値は正当な理由がない限りは返されるべきではありません。NS_NOINTERFACE を返すことが心配ならば、前のサンプルが示すように NS_OK を返してください。

see you in the soup.(^Q^)/"

Mozilla DOM Hacking Guide: Introduction to XPCOM 8

再び寒さが戻って着た。

ホリエモンファンのワイフの浮かない顔を後に、仕事部屋に入る。

静かな夜だ。パソコンのドライヴの音が、静かなうなりを上げている。

************************************

原文：　 青色表示
訳文：　 黒色表示
注記/訂正： 赤色表示

Let's say that you now want to execute a function declared on the nsIFoo2 interface, also implemented by nsFoo. However, ifooptr does not give you access to that function, since it is a pointer to nsIFoo, for the reasons mentioned in Section 1.B. XPCOM provides a handy method to get a pointer to an interface when you have a pointer to another interface, and both interfaces are implemented by the same object. This method is QueryInterface(). It is defined on the nsISupports interface. Every single interface in Mozilla inherits from nsISupports. This is one of the main rules of XPCOM. The goal is the following: find out whether an object (an instance of a class) implements a given interface. This is what QueryInterface() does. You pass an interface and the address of a pointer to store the interface to QueryInterface(). If the interface is implemented by the object, the pointer passed in will be assigned to the address of the object. If the interface is not implemented by the object, QueryInterface() will return NS_NOINTERFACE, and the pointer passed in will be null.

今 nsIFoo2 インターフェイスで宣言され、nsFoo で実装された関数を実行したいとしましょう。しかしこの時、ifooptr 経由ではその関数にアクセスできません。それは 1.B の節で述べた理由のために ifooptr が nsIFoo へのポインタだからです。XPCOM には便利なメソッドがあり、別のインターフェイスへのポインタがある時、インターフェイスへのポインタを持てます。そして、2 つのインターフェイスは同じオブジェクトによって実装されます。この時のメソッドが　QueryInterface() です。それは nsISupports インターフェイスで定義されます。Mozilla の各々のインターフェイスは nsISupports を継承しています。この事は、XPCOM の主要ルールの 1 つです。目的はこうです。オブジェクト（クラスのインスタンス）が所定のインターフェイスを実装するかどうかを知る。これが QueryInterface() の働きです。インターフェイスとインターフェイスを保持するポインタのアドレスを QueryInterface() に渡します。その時インターフェイスがオブジェクトによって実装されていれば、渡されたポインタはオブジェクトのアドレスを代入されます。もし実装されていなければ、 QueryInterface() は NS_NOINTERFACE を返し、渡されたポインタは null になります。

QueryInterface() is handy to hide the implementation of an object from the user. Just call QueryInterface() then call the method on the interface. You don't need to know anything else. So how do we use QueryInterface() to get a pointer to nsIFoo2 if we have a pointer to nsIFoo? Since we cannot re-use ifooptr, we create a new pointer to nsIFoo2, ifooptr2. The following syntax is the preferred one (to use only with nsCOMPtr's):

nsCOMPtr<nsIFoo2> ifooptr2 (do_QueryInterface(ifooptr));

QueryInterface() はユーザへオブジェクトの実装を隠蔽するのに便利です。 QueryInterface() をただ呼び出してから、インターフェイスのメソッドを呼び出します。その外は知る必要がありません。それでは、nsIFoo へのポインタがある時、どのように QueryInterface() を使って nsIFoo2 へのポインタを得るのでしょうか？　ifooptr を再利用できない以上、nsIFoo2 への新ポインタである ifooptr2 を作ります。以下の構文が（nsCOMPtr とだけ使う場合）推奨されます:

nsCOMPtr<nsIFoo2> ifooptr2 (do_QueryInterface(ifooptr));


That syntax is the preferred one to declare and initialize an nsCOMPtr at the same time. If you have to assign it another address later, you can easily do

ifooptr2 = do_QueryInterface(another_pointer);


この構文は nsCOMPtr の宣言と初期化を同時にするのに推奨されます。あとで、別のアドレスをそこへ代入する必要があるならば、簡単にこうできます

ifooptr2 = do_QueryInterface(another_pointer);



This syntax however is just a convenient shortcut to the real function. Below is how one would use the QueryInterface() function with raw pointers.

nsIFoo2 *ifooptr2;
ifooptr->QueryInterface(NS_GET_IID(nsIFoo2), (void **)&ifooptr2);


しかしこの構文は、単に実際の関数への便利なショートカットにすぎません。以下の構文は生のポインタで QueryInterface() を使用する方法を表します。

nsIFoo2 *ifooptr2;
ifooptr->QueryInterface(NS_GET_IID(nsIFoo2), (void **)&ifooptr2);


See you tomorrow (^-^)/~~~~

Mozilla DOM Hacking Guide: Introduction to XPCOM 7

本日は冬の寒さが緩んだ一日だった。床屋へ行った。12月の初旬以来１ヵ月ぶりになる。不思議なのは、年を取っても髪の伸びる速さは変わらないことだ。いや、むしろ若いころよりは、速く伸びるのではと思う程だ。髪の量は少なくなってきているのにさ。(-_-;

原文：　 青色表示
訳文：　 黒色表示
注記/訂正： 赤色表示

A getter is a function defined in global scope or in class scope that will "return" a pointer to the required interface. Generally getters work like this: First, declare a pointer to an interface, ifooptr without assigning it. Pass the address of the pointer to the getter function. The getter function will then assign to the pointer the correct address and will QueryInterface the pointer to that interface. ifooptr is now a pointer to an interface assigned to the address of a real object, and you can thus now call methods defined on nsIFoo through ifooptr. Here is some example code.

nsCOMPtr<nsIFoo> ifooptr;
GetInterfaceIFoo(getter_AddRefs(ifooptr));
ifooptr->FunctionOfnsIFoo();

getter は、グローバルな領域や、要求されたインターフェイスへポインタを”返す”クラスの領域で定義される関数です。一般的に　getter　は以下のように機能します:最初にインターフェイスへのポインタである ifooptr を代入なしに宣言します。それから、getter 関数へポインタのアドレスを渡します。この時 getter 関数は、ポインタへ適当なアドレスを代入し、インターフェイスへのポインタへ QueryInterface します。ifooptr はすでに、実際のオブジェクトのアドレスを代入されたインターフェイスへのポインタとなっています。このようにして、ifooptr 経由で nsIFoo で定義されたメソッドをすぐに呼び出せます。以下にコードの例を上げます。

nsCOMPtr<nsIFoo> ifooptr;
GetInterfaceIFoo(getter_AddRefs(ifooptr));
ifooptr->FunctionOfnsIFoo();

The peculiar syntax, getter_AddRefs(pointer), is the nsCOMPtr counterpart to the usual "&" (address-of) C++ operator. It means that the Getter method will call the AddRef method for you. This is a contract between the caller, who says "I don't add a reference to this object because you have already done it", and the callee who says "I add a reference to this object, so don't do it!". If both the caller and the callee perform the AddRef, the object will be leaked, because one of the two references will never be released!

独特の構文である getter_AddRefs(pointer) は、通常の "&" (address-of) C++ 演算子に対して nsCOMPtr が対応するものと同じです。すなわち、Getter メソッドは AddRef メソッドを呼び出します。これは、「このオブジェクトに参照を追加しません。もうすでにあなたが追加していますからね」という呼び出し元と「このオブジェクトへは私が参照を追加しますので、追加しないでください」という呼び出し先との間の契約になります。もし、呼び出し元と呼び出し先が両方で AddRef を実行すると、どちらかの参照は解放されないので、オブジェクトはメモリリークとなります。

Please note that all Getter functions have to AddRef the returned pointer. If you're just using the Getter function though, you don't need to worry about it. More about this in the XPCOM Ownership Guide.

すべての Getter 関数は返されたポインタを AddRef しなければならない ことに注意してください。それでも今 Getter 関数 を使用しているとしても、心配することはありません。 XPCOM 所有の手引きでは詳しい情報を参照できます。

Please also note that some interfaces are not refcounted, like the frames and views. For those you have to use raw interface pointers, and you don't have to perform any manual refcounting.

フレームやビューのように、インターフェイスには参照カウントされないものがあることにも注意してください。これらに対しては生のインターフェイスポインタを使用しなければなりません。マニュアルで参照カウントする必要はありません。

See you tomorrow!(^-^)/~~~~

Mozilla DOM Hacking Guide: Introduction to XPCOM 6

今日は冬にしては珍しく激しい雨となり、雷鳴が轟いた。駄文をものする。

子供が母親から授かるのは母性の優しさである。それは家庭にあってそこここに満ち溢れている。それでは父親からは何を授かるのであろうか。その1つは社会性かもしれない。一般的に父親は家庭の外で働く。そこでの経験から学んだ事をを父は子に伝えようとする。それは、自分の子供がやがては社会に出いくことを知っているからである。それではなぜ父は自分の経験を子に伝えようとするのだろうか？父の話が子にどれくらい伝わるか彼は分かっているのだろうか。もし、彼が父の話を聞く立場にある子ならば、どれくらに真剣に父の話をきくだろうか。その何パーセントを子は自分の経験に照らし合わせて、理解できるであろうか。普通、人は自分自身経験したことはよく理解できる。しかし経験のないことを聞いて、はたしてどのくらい分かって、それが彼の記憶にとどまるのだろうか。父は本当は自分の話が子にそれほど理解されない事を知っているのかもしれない。しかしそれでも話をする動機はなんだろうか。おそらく、子に理解して欲しいと思う願いはあるだろう。子にたいする愛情の形のひとつかもしれない。また、親の義務と感じているのかもしれない。

現代は父が子に語ることは少ない時代なのだろう。いや、従来から父は子に多くを語らない存在のような気がする。しかし、子と接する中で父は少ないながらも、今こそ自分の思いを子に語る時だと感じることがあると思う。けっして機会は多くないだろう。しかし、そんな瞬間は必ずある。そのように感じれば、父は話さずにおれない。彼は子を持つ父なのだから。(^_^ゞ

原文：　 青色表示
訳文：　 黒色表示
注記/訂正： 赤色表示

C. nsCOMPtr

Scott Collins blessed us with the nsCOMPtr, now let's use them. nsCOMPtr's are an extension of the C++ auto_ptr, managing the reference counting operations for you, and providing several facilities for comparison, initialization, etc... An nsCOMPtr is used like an usual pointer to an interface in most cases. An usual pointer to an interface nsIFoo is declared as follows:
　　nsIFoo *fooptr;

Scott Collins は私たちに nsCOMPtr を授けてくれたので、すぐにそれを使用しましょう。 nsCOMPtr は C++ auto_ptr の拡張機能で、参照カウントの操作を管理します。そして、比較、初期化などに対していくつかの機能を提供します。nsCOMPtr は大抵の場合インターフェイスへの通常のポインタのように使われます。nsIFoo インターフェイスへの通常のポインタは下記のように宣言されます:
　　nsIFoo *fooptr;

An nsCOMPtr to the same nsIFoo interface is declared as follows:
　　nsCOMPtr<nsIFoo> fooptr;

//同じnsIFoo インターフェイスへの nsCOMPtr は下記のように宣言されます:
　　nsCOMPtr<nsIFoo> fooptr;

nsCOMPtr's is described in the next Section. For more information about nsCOMPtr's, please read the User's Guide.

nsCOMPtr　を使用する場合のその他のケースは次の節で解説されます。nsCOMPtr　についての詳細情報は ユーザの手引きを読んでください。

D. QueryInterface()

Consider again the class nsFoo that implements two interfaces, nsIFoo and nsIFoo2:
class nsFoo : public nsIFoo, public nsIFoo2

再び、nsIFoo と nsIFoo2　の 2 つのインターフェイスを実装する nsFoo クラスを考えてください:
class nsFoo : public nsIFoo, public nsIFoo2
　　　　　　　　　　　　
Let's assume an instance of nsFoo was somehow created (this assertion is true most of the time). You would like to manipulate that object with a method defined on the nsIFoo interface. The goal is to retrieve a pointer to the nsIFoo interface. To do so, there are too main techniques, and the context should tell you what to use. The first technique is to use a "Getter", the second is to use a static cast on the "this" pointer.

ともかく nsFoo のインスタンスが作られることを前提としましょう（この断定はほとんど常に正しいです）。そうすると、nsIFoo　インターフェイスで定義されたメソッドを使ってそのオブジェクトを操作したくなるでしょう。目的は nsIFoo インターフェイスへポインタを確保することです。そのために、主な 2 つのテクニックが存在し、コンテキストによってするべきことが分かります。最初のテクニックは "Getter" を使うことであり、次のテクニックは "this" ポインタで　static なキャストを使うことです。

前節の "B. インターフェイスと参照カウント" は長い節でしたが、この” D. QueryInterface()”はもっと長いです。(・_・;

Mozilla DOM Hacking Guide: Introduction to XPCOM 5

相変わらず寒い夜だ。しかし、ふと思うと寒さがそれほど身に凍みなくなって来たようだ。昨年の12月のほううが余程辛かった。徐々に冬の寒さに慣れてきたのかもしれない。

冬の夜の楽しみは、晩酌の熱燗徳利だ。酒の刺激が胃から五臓六腑にしみわたる感じがなんとも言えない。そして、ほろ酔いで今日も仕事部屋へ入る。(=^-^=)

原文：　 青色表示
訳文：　 黒色表示
注記： 赤色表示

Note: the previous paragraph is extremely important. If you haven't grasped it completely, there is no need to read further.

注意: 前の段落は大変重要です。もしそれが完全に理解できていないならば、これ以上読み進める必要はありません。//入門書としては相当キツーイお言葉？

Reference counting basics

XPCOM uses a reference counting mechanism (refcount in short) to make sure that no object is deleted while interface pointers still point at that object. Indeed, dereferencing a pointer that points to a deleted object can have bad consequences. That is why each time a pointer to an interface is assigned the address of an object, we have to increase the reference count of that object by one. The function that does this is called "AddRef" and is defined in the nsISupports interface. When the pointer no longers holds the address of that object, it has to decrease the reference count of that object by one. This is done using the "Release" function, also defined in the nsISupports interface. When the reference count of an object hits 0 (zero), the object deletes itself. This is why it is very important to keep track of the reference count of each object. In the first case, if we forget to AddRef the object, the object may delete itself before we are done using the pointer, which would cause a crash when dereferencing it. In the second case, if we forget to Release the object, it will never delete itself, which will cause "memory leaks", i.e. the memory is never returned because we keep the object around even if we don't need it. In both cases it's very bad, and we have to be extremely careful with the refcounting.

参照カウントの基本

XPCOM は参照カウントのメカニズム(短縮形 refcount )を使って、インターフェイスのポインタがオブジェクトを指している間にオブジェクトが削除されていないことを確認します。事実、削除されたオブジェクトを指し示すポインタを間接参照することは悪い影響を及ぼす可能性があります。そんな訳で、インターフェイスへのポインタがオブジェクトのアドレスを代入される都度、そのオブジェクトのカウントを一つ増やす必要があります。これを実行する関数は、”AddRef”と呼ばれ、nsISupports インターフェイスで定義されます。ポインタがすでにオブジェクトのアドレスを保持しない時、そのオブジェクトの参照カウントを一つ減じる必要があります。これには同じく、nsISupports インターフェイスで定義された”Release”関数を使用します。オブジェクトの参照カウントが 0(zero) に達するとオブジェクトは自分自身を削除します。こんなわけで、各々のオブジェクトの参照カウントの記録を確保することは大変重要になります。最初のケースでは、もし AddRef を使ってオブジェクトのカウントを増やすのを忘れると、私たちがポインタ使用して何かする前にオブジェクトは自分自身を削除するかもしれません。そのために、間接参照される時に、クラッシュを引き起こすことがあります。次のケースでは、もしオブジェクトを Release 関数を使って開放することを忘れると、オブジェクトは自分自身を削除しません。それで、たとえば”メモリリーク”を発生させ、不要になってもオブジェクトを確保しているので、メモリがシステムに返されることはありません。どちらのケースも不都合なので、参照カウントには細心の注意を払わなくてはなりません。

Fortunately, there are nsCOMPtr's to make our life easier.

幸運にも、 nsCOMPtr があって私たちの活動をより楽にしてくれます。


これで長い長いインターフェイスに関する節が完了した。(^Q^)/"

Mozilla DOM Hacking Guide: Introduction to XPCOM 4

昨日の続きです。

原文：　 青色表示
訳文：　 黒色表示
注記： 赤色表示

That object can then be manipulated only through fooptr. Let's consider what happens when the class nsFoo implements an interface nsIFoo. You can manipulate the nsFoo object directly through fooptr, however your code will not be very robust. Indeed, if someone decides to change the name or the signature of the methods you use, you will have to change all the calls to those methods throughout your code. As opposed to a concreate class, an interface is supposed to be more stable through time. Indeed, many interfaces in the Mozilla code are frozen (this is indicated by the comment @Frozen a the begining of the interface definition). That means that the interface will never change anymore. The good thing is that your code will (in the best condition) last forever. The bad thing is that we have to find a way to improve those interfaces, and freezing them obliges implementers to create new interfaces. In summary, manipulate an interface rather than its implementation whenever possible! A pointer to an interface nsIFoo implemented by nsFoo can be declared as follows
nsIFoo *fooptr = new nsFoo;

その時オブジェクトは、 fooptr 経由でのみ操作されます。この時、nsFoo クラスが nsIFoo インターフェイスを実装するならどうなるかを考えてみましょう。nsFoo オブジェクトを fooptr 経由で直接操作可能ですね。しかし、コードはあまり頑健ではありません。事実、使われているメソッドの名前やシグニチャーを変更する者がいると、全コードに渡りこれらのメソッドへの呼び出しをすべて変えなければなりません。具象クラスとは反対に、インターフェイスは時が経過しても安定しているはずです。事実、Mozilla コードの多くのインターフェイスは凍結されて（インターフェイス定義の最初に @Frozen コメントで指示されて）います。これは、それらのインターフェイスがこの先変わることがないという意味です。メリットは、こうして作られたコードが将来永遠に（最高の条件で）存在し続けることです。反対に欠点は、これらのインターフェイスを改善する方法を見つけ凍結するには、実装しようと思えば新しいインターフェイスを作らなければならないことです。要するに、必要な時はいつでも実装ではなくインターフェイスを操作することです。nsFoo によって実装される nsIFoo インターフェイスへのポインタは以下のように宣言されます。
nsIFoo *fooptr = new nsFoo;

A pointer such as fooptr is then called a "pointer to an interface nsIFoo implemented by an instance of the nsFoo class", or "pointer to nsIFoo" in short. From now on, when I speak of a "pointer to an interface", I really mean a "pointer to an interface implemented by an instance of a concrete C++ class". The important thing to note is that a pointer to nsIFoo can only call the methods defined on the nsIFoo interface, and on its parents. For instance, if nsFoo implements two different interfaces, nsIFoo and nsIBar, a pointer to nsIFoo cannot call the methods defined on nsIBar and vice-versa.

fooptr のようなポインタはその時、 ”nsFoo クラスのインスタンスによって実装される nsIFoo インターフェイスへのポインタ”とか、それを短縮して”nsIFoo へのポインタ”と呼ばれます。今後、私が”インターフェイスへのポインタ”について言う時は、”C++ の具象クラスのインスタンスによって実装されたインターフェイスへのポインタ”を事実上意味します。注意すべき重要点は、nsIFoo へのポインタのみが nsIFoo インターフェイスやその親で定義されたメソッドを呼び出せることです。たとえば、nsFoo が nsIFoo と nsIBa というふたつの異なるインターフェイスを実装するなら、nsIFoo へのポインタは nsIBa で定義されたメソッドを呼び出せません。その逆もありません。

See you tomorrow (^-^)/~~~~

Mozilla DOM Hacking Guide: Introduction to XPCOM 3

"B.インターフェイス"の節を続けて和訳します。

原文：　 青色表示
訳文：　 黒色表示
注記： 赤色表示


An interface is thus simply a C++ class where all the member functions are declared as pure virtual functions. An interface can also be defined using XPIDL. This is described in Section 1.E, "How to add an interface".

インターフェイスはこのようにすべてのメンバ関数が純粋に仮想関数として宣言される、単に C++ のクラスです。インターフェイスはまた XPIDL を使って定義されます。この件は、 1.E の節”新インターフェイスの追加方法”で解説されます。

Since an interface doesn't have any implementation, it has to be implemented by a non-abstract class -- a concrete class. If the interface is called nsIFoo and the class is called nsFoo, we say that "nsFoo implements nsIFoo", or that "nsFoo inherits from nsIFoo". The C++ code is the following:
　class nsFoo : public nsIFoo

インターフェイスは実装を備えていないので、非抽象クラス（具体的クラス）によって実装される必要があります。その際、インターフェイスが nsIFoo と呼ばれるならば、クラスは nsFoo と呼ばれます。その時、"nsFoo は nsIFoo を実装する"とか"nsFoo は nsIFoo を継承する"と言います。C++ のコードは次のようになります:
　class nsFoo : public nsIFoo

For those unfamiliar with object-oriented C++, this means that nsFoo is declared as "derived from" nsIFoo, and that nsIFoo is a "base class" of nsFoo. For this introduction you don't need to know more about object-oriented C++. However the Section 1.F provides a more detailed discussion about it, and is necessary to understand most of the DOM code.

オブジェクト指向の C++ を知らない人のために言うと、nsFoo は nsIFoo からの”派生”として宣言されることになります。そしてこの時、nsIFoo は nsFoo の”基底クラス”になります。この入門書では、オブジェクト指向の C++ についてもっと多くを知る必要はありません。しかし、1.F 節ではその件でさらに詳しい議論があり、DOM コードのほとんどを理解することが必要になります。

An instance of a class (called an object) can be allocated dynamically (on the heap, or free store), using the syntax
nsFoo *fooptr = new nsFoo;

（オブジェクト）と呼ばれるクラスのインスタンスは（ヒープや空き領域に）、下記の構文を使って動的に割り付けられます
nsFoo *fooptr = new nsFoo;

(^-^)/~~~~

Mozilla DOM Hacking Guide: Introduction to XPCOM 2

さて、タイトルの文書の草稿作成のため和訳をすすめています。
まだ粗稿の段階何なので、文章がこなれていませんが。(・_・;

原文：　 青色表示
訳文：　 黒色表示
注記： 赤色表示


Introduction to XPCOM for the DOM
A. Introduction to the introduction
The DOM makes extensive use of XPCOM. In fact, to do anything with the DOM implementation you need XPCOM. You do not, however, need to know all the hairy details, if you just intend to read the code or to work with the existing framework. The numerous macros and facilities brought by the DOM, as well as nsCOMPtr's, make our life much easier. In this chapter I will attempt to cover the most widespread use of XPCOM in the DOM, avoiding the details as much as possible. I will introduce nsCOMPtr's, interfaces, reference counting, and the nsISupports interface. A tutorial about how to add a new interface is also provided, and eventually, a more detailed discussion of class inheritance in C++.


DOM のための XPCOM 入門
A. 入門への手引き
DOM は XPCOM を広く使います。事実、 DOM を実装して使用するには XPCOM が必要になります。しかし、コードを読んだり既存のフレームワークに何かするだけならば、詳細まで知る必要はありません。nsCOMPtr も含めて DOM が提供する数多くのマクロや機能は私たちの活動をとても楽にしてくれます。この章では、できるだで枝葉末節の解説を避けて DOM でごく共通に使われている XPCOM の範囲をカバーしたいと思います。そして nsCOMPtr のインターフェイス、参照カウント、 nsISupports インターフェイスを解説します。新インターフェイスの追加方法のチュートリアルや、最後に C++ におけるクラスの継承についての詳細の議論についても解説します。

B Interfaces

Object-oriented programming is based on the used of inheritance between classes. Furthermore, a class can be de declared to be "abstract" if it declares some methods but does not implement them entirely. Pushing this concept to its maximum, a class can be "purely virtual" if it declares methods without implementing any of them. Such a class is called an interface. The goal of interfaces is to have a single ... interface to a set of methods that manipulate an object (often represented by a class), without worrying about the details of the implementation. If you know a class implements an interface, just use the methods in the interface, and you don't have to care if the implementation of the interface (the concrete class) changes. XPCOM pushes this concept to the extreme. Pure virtual methods are declared with the following syntax:

virtual nsresult FunctionFoo() = 0;

B インターフェイス

オブジェクト指向のプログラミングは クラス間の継承の使用を基本にしています。さらに、メソッドを宣言して完全には実装しない限り、クラスは”抽象クラス”として宣言することができます。この考えを最大限に発揮することでクラスは、メソッドを実装せずに宣言するだけで、”完全に抽象的//→”完全な抽象クラス”のほうがいい？”になります。そのようなクラスはインターフェイスと呼ばれます。インターフェイスの目的は、ひとつのインターフェイスに・・・実装の詳細内容を心配することなく、（普通クラスとして表される）オブジェクトを操作する一セットのメソッドを持たせることです。もしクラスがインターフェイスを実装することをご存知ならば、その時インターフェイスにメソッドを使ってください。すると、インターフェイスの実装（具体的なクラス）が変わるかどうか気にする必要はありません。XPCOM はこの考えを究極まで推進しています。純粋な抽象メソッドが以下の構文で宣言されます:

virtual nsresult FunctionFoo() = 0;

(^-^)/~~~~