【はじめに】

この文書は KbMedia Player を制御するアプリケーションを作りたい開発者の方、ある
いは KbMedia Player をコマンドラインから制御したい人を対象としています。
一般ユーザーがお読みになる必要はありません。

KbMedia Player は DDE（Dynamic Data Exchange）によって外部アプリケーションから
制御する場合のサーバーとしての機能を備えています。

KbMedia Player を DDE で制御するプログラムのサンプルは

  Kobarin のホームページ：http://hwm5.gyao.ne.jp/kobarin/

で dde_test をダウンロードして下さい。


【概要】

DDE のサービス名とトピック名は "KbMedia Player" です。（" は含まない）
XTYP_EXECUTE と XTYP_REQUEST をサポートしています。
起動済み Mutex オブジェクトの名称も "KbMedia Player" です。

KbMedia Player を制御するアプリケーションは、レジストリの

  HKEY_CURRENT_USER\Software\Kobarin's Soft\KbMIDI Player\SearchPath\Kbmplay

を参照することにより、KbMedia Player の実行ファイルが置かれている場所を取得す
ることが出来ます。将来的には、

  HKEY_CURRENT_USER\Software\Kobarin's Soft\KbMedia Player\Path\Kbmplay

に変更する予定ですが、色々事情があってしばらくの間変更できません。将来に備え
て、KbMedia Player\Path\ の方を先に調べて、情報を取得できなかったら 
KbMIDI Player\SearchPath\ の方を調べるようにした方が良いかもしれません。


【XTYP_EXECUTE で使用可能なコマンド】（起動時のコマンドラインとしても使えます）

XTYP_EXECUTE と起動時のコマンドライン引数とは書式が共通しています。

/play       ：演奏開始（再生中の場合は最初から演奏開始）
/p          ：演奏開始（再生中の場合は何もしない）
              ・/play, /p ともに、ファイル名とともに渡された場合は一番最初に渡
                されたファイルを直ちに演奏開始します。
              ・起動時（起動済みでない）のコマンドラインにファイル名を渡さずに
                /play や /p をつけた場合は、前回終了時に開いたファイルを直ちに
                演奏開始します。ただし、多重起動の場合は、/play の場合は最初か
                ら演奏開始しますが、/p の場合はすでに演奏中だったときは何もし
                ません。ショートカットの実行時引数で指定する場合は /p の方が良
                いと思います。
/np         ：演奏を開始しない
              ・リストに追加したいだけの場合に指定します。
/a          ：リストに追加
/na         ：リストに追加しない
/stop       ：演奏停止
/pause      ：一時停止・再開（演奏中は一時停止、一時停止時は演奏再開）
/clear      ：リストを破棄（確認しない）
/seek:xx    ：xx の位置にシーク（xx は h:m:s, s(秒), ms(ミリ秒) の３通りが指定
              可能。単位を省略した場合は秒と見なす。秒は小数点も使用可能）
              例１：/seek:1:35
              例２：/seek:95
              例３：/seek:95s
              例４：/seek:95000ms
              例５：/seek:1:35.75
              例６：/seek:95.75
              例７：/seek:95.75s
              例８：/seek:95750ms

              例１〜例４は同じ意味。例５〜例８は同じ意味

/fadeout:xx ：フェードアウト（xx はフェードアウト時間、書式は seek と同様で、省
              略した場合はプレイヤーの設定に依存）

/tray       ：タスクトレイに格納
              ・起動時のコマンドラインにつけた場合はタスクトレイに入った状態で
                起動しますが、一瞬ウィンドウが表示されてしまいます。この問題は
                今のところ、「仕様」とさせて下さい。(^^;

/mx         ；Media エクスプローラにタブを切り替え
              /mx:"ファイル名" とすると、渡されたファイルを選択した状態で Media
              エクスプローラにタブを切り替えます。

/restore    ：タスクトレイ復帰
/next       ：次の曲
/prev       ：前の曲
/r1         ：単曲リピート有効
/nr1        ：単曲リピート無効
/quit       ：KbMedia Player を終了
/fileclose  ：演奏中のファイルを閉じる
              主にタグエディタとの連携の為のコマンドです。KbMedia Player が再生
              中のファイルは演奏が止まっていてもファイラーでの削除・移動やタグ
              エディタでの書き換えに失敗します。
              事前に /fileclose しておくことで回避出来るようになります。

・各種コマンドの大文字と小文字は区別しません。例えば /tray と /Tray と /TRAY は
  同じ意味
・ファイル名にスペースを含む場合は "" で括らなければならない
・ファイル名にスペースを含まない場合は "" で括っても括らなくてもどちらでも良い
・複数のファイル名を渡した場合や、ディレクトリ・アーカイブ・演奏リスト・１ファ
  イルに複数曲含むデータを渡した場合は /a, /na は無視して常にリストに追加する

・ファイル名が渡されていて、かつ /p, /np, /a, /na などが省略されていた場合の動
  作はドラッグアンドドロップ時の動作と同じになります。すなわち、
  ・Ctrl だけが押されている場合は「リストに追加＋演奏開始」（/a /p）
  ・Shift だけが押されている場合は「リストに追加」（/a /np）
  ・Ctrl と Shift の両方が押されている場合は「新規に追加」（リストを破棄してか
    ら「リストに追加＋演奏開始」）（/a /p /clear）
  ・Ctrl, Shift がどちらも押されていない場合は Media エクスプローラの「ダブルク
    リック時」の設定に従う）


例１：

C:\aaa.mp3 /na /p

aaa.mp3 をリストに追加しないで演奏（Media エクスプローラの「追加しないで演奏」
に相当）


例２：

"C:\hoge hoge" /p /clear

リストを破棄し、"C:\hoge hoge" をリストに追加し、検索で一番最初に見つかったも
のを再生する。（Media エクスプローラの「新規に追加」に相当）
（"C:\hoge hoge" は名前にスペースを含むので "" で括らなければならない）


例３：

C:\aaa.lzh /np

aaa.lzh 内の全サウンドデータをリストに追加する。ただし、再生はしない。
（Media エクスプローラの「追加」に相当）


例４：

"C:\aaa.lzh>bbb/ccc.mid" /a /p /tray

aaa.lzh>bbb/ccc.mid をリストに追加して再生する。タスクトレイにも格納する。
（起動時のコマンドラインで > を渡す場合はファイル名を "" で括る必要があります）


例５：

"C:\aaa.mp3" "D:\bbb.mid" /seek:60 /p

aaa.mp3 と bbb.mid をリストに追加し、aaa.mp3 を 60 秒の位置から演奏開始。
（/seek と 60 の間には : が必ず必要です）


例６：

C:\aaa.mp3 C:\bbb.mid C:\ccc.spc

（/np or /p が省略されているので）aaa.mp3 と bbb.mid と ccc.spc をドラッグアン
ドドロップしたときの動作と同じ動作

例７：

C:\aaa.nsf::0005 /na /p

aaa.nsf の５番目の曲をリストに追加しないで再生する



【XTYP_REQUEST で使用可能なコマンド】

大文字と小文字は区別しません。例えば Status と status は同じと見なします。
すべての戻り値は文字列（終端の \0 を含む）です。
認識しないコマンドなどが渡された場合は NULL を返します。


status  ：再生状態を返す。戻り値は
           ・Playing（演奏中）
           ・Stop（演奏停止）
           ・Pause（一時停止）
           ・Seeking（シーク中）
position：再生位置をミリ秒単位で返す。
title   ：再生中のサウンドのタイトルを返す
artist  ：再生中のサウンドのアーティストを返す
          他にも kmp_pi.h で定義されている SZ_KMP_TAGINFO_NAME_XXXX が利用可能
          です。 title/artist の他に

          album/genre/date/comment/albumartist/bitrate/tracknumber/discnumber/
          tracktotal/disctotal/replaygain_track_gain/replaygain_track_peak/
          replaygain_album_gain/replaygain_album_peak 

          などがあります。KbMedia Player のバージョンによっては取得に未対応な場
          合があります。未対応な名前が渡された場合は NULL を返します。 
length  ：再生中のサウンドの曲の長さをミリ秒単位で返す。長さがわからない場合は 
          -1 を返す
fileName：再生中のサウンドのファイル名を返す。戻り値の例は以下の通り

            例１：C:\hogehoge\aaa.mp3
            例２：C:\hogehoge.lzh>aaa/bbb.mid 
            例３：C:\hogehoge.rar>aaa/bbb.zip>ccc/ddd.spc
            例４：X:\::AudioCD::####
            例５：D:\emusound\aaa.nsf::0003

            例２〜例５のように、戻り値の文字列が必ずしもファイルとして存在する
          とは限らないことに注意

listfilename：現在開いているプレイリストファイルのファイル名を返す。圧縮ファ
              イル内のプレイリストファイルにも対応していることに注意。新規に作
              成されている場合は空文字列を返す

listcount ：プレイリストに登録されている曲の数を返す

supportext：対応しているサウンドファイル形式の拡張子（ピリオドも含む）を返す。
            拡張子はセミコロンで区切る。例えば

              .AAC;.MID;.MP3 

            のような文字列を返す。将来的に先頭にピリオドを含まないものを返す可
            能性もあるが、その場合は無視すること（.AAC;.MID;.MP3;AAAA;BBBB が
            返って来た場合は AAAA と BBBB は無視する）

supportarc：対応しているアーカイブ形式の拡張子を返す。書式は SupportExt と同じ

exename   ：KbMedia Player の実行ファイル名（フルパス）を返す

version   ：KbMedia Player のバージョンを返す
