Tools.h++ 7.0 クラスライブラリ・リファレンスマニュアル: RWDDEstreambuf

バナーをクリックすれば目次に戻ります

Copyright 1999 Rogue Wave Software
Copyright 1999 Sun Microsystems, Inc.

## RWDDEstreambuf

RWDDEstreambuf RWCLIPstreambuf streambuf

### 形式

      #include <rw/winstrea.h>
      #include <iostream.h>
      iostream str( new RWDDEstreambuf(CF_TEXT, TRUE, TRUE, TRUE) ) ;

### 説明

  クラス RWDDEstreambuf は、`GMEM_DDESHARE` フラグ付きで割り当てられた Microsoft Windows 大域メモリーとの間で一連の文字を読み書きするための専用 streambuf です。Windows の動的データ交換 (DDE) 機能を通して、データを交換するのに使用できます。

  このクラスには、動的と静的の 2 つの動作モードがあります。動的モードでは、必要に応じてメモリーの割り当てと再割り当てが行われます。内部バッファーの現在のサイズに比べて挿入する文字数が多すぎる場合、バッファーのサイズが変更され、必要に応じて古い文字が新しいメモリーにコピーされます。これはユーザーには見えません。このモードは、主に DDE サーバが使用するためのものです。静的モードでは、バッファー streambuf は特定のメモリー領域から作成されます。再割り当ては行われません。このモードは、主に DDE クライアントが使用するためのものです。

  動的モードでは、RWDDEstreambuf は、メンバー関数 `str()` が呼び出されるまで、割り当てられたメモリーを「所有」します。`str()` はバッファーを「フリーズ」し、ロック解除された Windows ハンドルを RWDDEstreambuf に返します。それ以上挿入した場合の影響は定義されていません。`str()` が呼び出されるまでは、割り当てられたメモリーを解放するのは RWDDEstreambuf デストラクタの責任です。`str()` が呼び出された後は、ユーザーの責任になります。

  静的モードでは、メモリーハンドルを解放するのはユーザーの責任です。ただし、コンストラクタがハンドルをロックして間接参照するので、デストラクタか `str()` が呼び出されるまで、ユーザーはメモリーを解放してはなりません。デストラクタと `str()` のどちらかがハンドルをロック解除します。

  ユーザーがメモリーの解放に「責任」を持っていることもありますが、実際に `GlobalFree()` を呼び出すのがクライアントかサーバーかは、DDE の「リリース」フラグによって決まることに注意してください。

### 持続性

  なし

### 例

  これは DDE サーバーによるクラスの使用方法を示す例です。

      #include <rw/winstrea.h>
      #include <iostream.h>
      #include <windows.h>
      #include <dde.h>

      BOOL
      postToDDE(HWND hwndServer, HWND hwndClient) {
        RWDDEstreambuf* buf =
        new RWDDEstreambuf(CF_TEXT, TRUE, TRUE, TRUE);
        ostream ostr(buf);
        double d = 12.34;
        ostr << "Some text to be exchanged through the DDE.\n";
        ostr << "The double you requested is: " << d << endl;
        ostr.put(0);  // 終端ヌルを付ける
        // streambuf をロックして、そのハンドルを獲得する
        HANDLE hMem = buf->str();
        // 識別アトムを獲得する
        ATOM aItem = GlobalAddAtom("YourData");
        if(!PostMessage(hwndClient, WM_DDE_DATA, hwndServer,
                        MAKELONG(hMem, aItem))){
          // メッセージポストが失敗。おそらくクライアントが終了したため。
          // この場合、メモリーの割り当てを解除する責任はユーザーにある
         if( hMem != NULL )
         GlobalFree(hMem);
         GlobalDeleteAtom(aItem);
         return FALSE;
        }
        return TRUE;
      }

  DDE サーバーのハンドルは、パラメータ `hwndServer` として、クライアントのハンドルはパラメータ `hwndClient` として渡されます。関連する streambuf として RWDDEstreambuf を使用して、ostream が作成されます。結果は、Windows 大域メモリーに文字が挿入される以外は、cout などの他の ostream とほぼ同様に使用でき、それから DDE を通して転送することができます。コンストラクタで使用されるパラメータに注意してください。これらは、DDE を通してメモリー割り当てを処理する方法に関して重要な分枝点となるので、以下で検討する必要があります。特に、パラメータ `fRelease` が `TRUE` の場合には、完了時にクライアントがメモリーの解放に責任があることを示します。デフォルトでも、`fAckReq` `TRUE` を指定します。すなわち、クライアントがメッセージの受信を確認することを意味します。したがって、ユーザーがメッセージを受信する準備をしなければなりません。

  いくつかのテキストと倍精度浮動小数点数が ostream に挿入されます。次に、Windows の `HANDLE` をロック解除して返すメンバー関数 `str()` が呼び出されます。一度 `str()` を呼び出すと、このメモリーに関する責任はユーザーにあり、完了時にはそれを解放するか、他の誰かに責任を渡さなければなりません。この場合、クライアントに責任が移ります。

  次に、データを特定するためにアトムが作成されます。DDE データが識別用アトムとともに送信されます。送信に失敗した場合は、大域メモリーに対する責任を他の誰かにを押しつけることができないため、ユーザー自身がそれを (アトムとともに) 解放しなければなりません。

### 公開コンストラクタ

      RWDDEstreambuf(WORD cfFormat = CF_TEXT,
                     BOOL fResponse = TRUE
                     BOOL fAckReq   = TRUE
                     BOOL fRelease  = TRUE);

    空の RWDDEstreambuf を動的モードで作成します。結果は、他の streambuf を使用できる場合はどこでも使用できます。必要に応じて、新しい文字を入れるメモリーが割り当てられます。

    『Windows Reference, Volume 2』に 4 つのパラメータが定義されています (特に、「DDE Message Directory」の節を参照してください)。パラメータ `cfFormat` は streambuf に挿入されるデータの形式を指定します。これらの形式は、`SetClipboardData()` で使用するものと同じです。単純な ostream ではなく、RWbostream や RWpostream などの特殊化仮想ストリームクラスを使用して、実際の文字挿入を実行する場合、形式はもっと複雑になります。この場合、ユーザーは Windows 関数 `RegisterClipboardFormat()` を使用して自分の形式を登録しておくことができます。

    他の 3 つのパラメータの意味については、下記または『Windows Reference Manual』を参照してください。

      RWDDEstreambuf(HANDLE hMem);

    大域ハンドル `hMem` を持つメモリーブロックを使って、RWDDEstreambuf を静的モードで作成します。このメモリーブロックのサイズを超えて、読み書きを行った場合の影響は定義されていません。DDE 転送の形式と、DDE 確認、メモリー割り当てなどの詳細は、次に定義するメンバー関数を使って獲得できます。

### 公開デストラクタ

      ~RWDDEstreambuf();

    メンバー関数 `str()` が呼び出されていない場合、デストラクタがハンドルをロック解除し、動的モードであればそれを解放します。

### 公開メンバー関数

  RWDDEstreambuf は `streambuf` から継承するため、後者のメンバー関数のどれでも使用できます。さらに、RWDDEstreambuf は strstreambuf に類似した設計となっています。ただし、`str()` の戻り型は `char*` ではなく `HANDLE` であることに注意してください。

      BOOL
      ackReq() const;

    この DDE 交換要求が確認を要求するかどうかを返します。詳細については、『Windows Reference, Volume 2』を参照してください。

      WORD
      format() const;

    この DDE 交換の形式 (たとえば、テキスト交換の場合は `CF_TEXT`) の形式を返します。詳細については、『Windows Reference, Volume 2』を参照してください。

      BOOL
      release() const;

    `str()` が返したメモリーの解放の責任がクライアントにある場合は、`TRUE` を返します。詳細については、『Windows Reference, Volume 2』を参照してください。

      BOOL
      response() const;

    `WM_DDE_REQUEST` メッセージに対する応答中にこのデータがある場合は、`TRUE` を返します。ここにデータがない場合は、`WM_DDE_ADVISE` メッセージへの応答中にあります。詳細については、『Windows Reference, Volume 2』を参照してください。

      HANDLE
      str();

    使用する大域メモリーへの (ロック解除された) `HANDLE` を返します。ここで、RWDDEstreambuf は「フリーズしている」ものとみなす必要があります。それ以上文字を挿入した場合の影響は定義されていません。RWDDEstreambuf が動的モードで作成され、何も挿入されていない場合は、`NULL` の `HANDLE` が返されることがあります。静的モードで作成された場合は、RWDDEstreambuf を作成するのに使用されたハンドルが返されます。