ソース管理プラグインを実装するためのベスト プラクティス
以下の技術的詳細は、Visual Studio でソース管理プラグインを確実に実装する助けとなります。
メモリ管理に関する問題
ほとんどの場合、呼び出し元である統合開発環境 (IDE) が、メモリの解放と割り当てを行います。 ソース管理プラグインは、呼び出し元が割り当てたバッファーで、文字列やその他の項目を返します。 例外については、発生場所となる特定の関数の説明に記載しています。
ファイル名の配列
ファイルの配列が渡されるときには、ファイル名の切れ目のない配列としては渡されません。 これはファイル名へのポインターの配列として渡されます。 たとえば SccGet では、lpFileNames パラメーターによってファイル名が渡されますが、lpFileNames は実際には char ** へのポインターです。 lpFileNames[0] は最初の名前へのポインター、lpFileNames[1] は 2 番目の名前へのポインターであり、これが続きます。
大きなモデル
16 ビット オペレーティング システム上であっても、すべてのポインターが 32 ビットです。
完全修飾パス
引数としてファイル名またはディレクトリを指定する場合は、末尾にバックスラッシュを付けず、完全修飾パスまたは UNC パスにする必要があります。 それが、基になっているソース管理システムの要件である場合は、ソース管理プラグインで、これらを相対パスに変換する必要があります。
登録される DLL の完全修飾パスを指定する
IDE では、相対パス (.\NewProvider.DLL など) から DLL を読み込まなくなっています。 DLL への完全なパスを指定する必要があります (C:\Providers\NewProvider.DLL など)。 この要件によって、未認可であったり偽装されていたりするソース管理 DLL の読み込みを防止し、IDE のセキュリティが強化されています。
ソース管理プラグインをインストールするときに既存の VSSCI プラグインについて調べる
ソース管理プラグインをインストールする予定のユーザーは、コンピューターに従来のソース管理プラグインを既にインストールしている場合があります。 関連するレジストリキーに既存の値があるかどうは、作成するプラグインのインストール (セットアップ) プログラムで判定する必要があります。 これらのキーが既に設定されている場合、インストール プログラムでは、そのプラグインを既定のソース管理プラグインとして登録するか、既にインストールされているものを置き換えるかをユーザーに確認する必要があります。
エラーの結果コードとレポート
ソース管理関数の SCC_OK リターン コードは、操作がすべてのファイルについて成功したことを示します。 操作が失敗した場合は、最後に発生したエラー コードが返されると予期されています。
レポートに関する規則では、IDE でエラーが発生した場合は、それを報告する責任を負うのは IDE です。 ソース管理システムでエラーが発生した場合は、それを報告する責任を負うのはソース管理プラグインです。 たとえば、IDE からは "現在どのファイルも選択されていません" と報告されるのに対して、プラグインからは "このファイルは既にチェックアウトされています" と報告されます。
コンテキスト構造体
SccInitialize の呼び出し中に、呼び出し元は ppvContext パラメーターを渡します。これは、void への初期化されていないハンドルです。 ソース管理プラグインでは、このパラメーターを無視することも、任意の種類の構造体を割り当てて、その構造体へのポインターを、渡されたポインターに入れることもできます。 IDE ではこの構造体は認識されませんが、この構造体へのポインターを、プラグイン内のその他の呼び出しすべてに渡します。 これによってプラグインに、有用なコンテキスト キャッシュ情報が提供されます。この情報を使用すると、グローバル変数を使用せずに複数の関数呼び出しにわたって存続するグローバル状態情報を維持できます。 プラグインは、SccUninitialize の呼び出しに関する構造体を解放する役割を担います。
プラグインによって SccInitialize に (具体的には lpSccCaps パラメーター内に) SCC_CAP_REENTRANT ビットが設定された場合、開いているすべてのプロジェクトを追跡するために複数のコンテキスト構造体が使用されます。
ビットフラグとその他のコマンド オプション
SccGet などの各コマンドに対して、IDE ではコマンドの動作を変更する多くのオプションを指定できます。
API では、IDE による、fOptions パラメーターを通した特定のオプションの設定をサポートしてい ます。 これらのオプションについては、それらの影響を受けるコマンドと共に、「特定のコマンドで使用されるビットフラグ」で説明されています。 これらは一般に、ユーザーにプロンプトが表示されないオプションです。
ユーザーが構成できる設定オプションのほとんどは、ソース管理プラグイン間で大幅に異なるため、この方法では定義されません。したがって、推奨されるメカニズムは [詳細設定] ボタンです。 たとえば、[取得] ダイアログ ボックスでは、IDE で認識されている情報のみが表示されますが、プラグインにこのコマンド用のオプションがある場合は、[詳細設定] ボタンも表示されます。 ユーザーが [詳細設定] ボタンをクリックすると、IDE から SccGetCommandOptions が呼び出されて、ソース管理プラグインで、ビットフラグや日付/時刻などの情報を求めるダイアログをユーザーに表示できるようになります。 プラグインからは、SccGet コマンドの実行時に返す構造体で、この情報が返されます。