USB クライアントドライバーコード構造について (UMDF)

[アーティクル]
01/17/2024

このトピックでは、UMDF ベースの USB クライアントドライバーのソースコードについて説明します。コード例は、Microsoft Visual Studio に含まれている USB ユーザーモードドライバー テンプレートによって生成されます。テンプレートコードは、アクティブテンプレートライブラリ (ATL) を使用して COM インフラストラクチャを生成します。 ATL とクライアントドライバーの COM 実装の詳細については、ここでは説明しません。

UMDF テンプレートコードの生成手順については、「最初の USB クライアントドライバー (UMDF) を記述する方法」を参照してください。テンプレートコードについては、次のセクションで説明します。

ドライバーコールバックのソースコード
デバイスコールバックのソースコード
キューのソースコード
ドライバーエントリのソースコード

テンプレートコードの詳細について説明する前に、UMDF ドライバー開発に関連するヘッダーファイル (Internal.h) 内のいくつかの宣言を見てみましょう。

Internal.h には、Windows Driver Kit (WDK) に含まれる次のファイルが含まれています。

#include "atlbase.h"
#include "atlcom.h"

#include "wudfddi.h"
#include "wudfusb.h"

Atlbase.h と atlcom.h には、ATL サポートの宣言が含まれています。クライアントドライバーによって実装される各クラスは、ATL クラス public CComObjectRootEx を実装します。

Wudfddi.h は、UMDF ドライバー開発に常に含まれています。ヘッダーファイルには、UMDF ドライバーをコンパイルするために必要なメソッドと構造体のさまざまな宣言と定義が含まれています。

Wudfusb.h には、フレームワークによって提供される USB I/O ターゲットオブジェクトと通信するために必要な UMDF 構造とメソッドの宣言と定義が含まれています。

Internal.h の次のブロックは、デバイスインターフェイスの GUID 定数を宣言します。アプリケーションはこの GUID を使用して、SetupDiXxx API を使用してデバイスへのハンドルを開くことができます。 GUID は、フレームワークがデバイスオブジェクトを作成した後に登録されます。

// Device Interface GUID
// f74570e5-ed0c-4230-a7a5-a56264465548

DEFINE_GUID(GUID_DEVINTERFACE_MyUSBDriver_UMDF_,
    0xf74570e5,0xed0c,0x4230,0xa7,0xa5,0xa5,0x62,0x64,0x46,0x55,0x48);

次の部分では、トレースマクロとトレース GUID を宣言します。トレース GUID をメモします。トレースを有効にするには必要です。

#define WPP_CONTROL_GUIDS                                              \
    WPP_DEFINE_CONTROL_GUID(                                           \
        MyDriver1TraceGuid, (f0261b19,c295,4a92,aa8e,c6316c82cdf0),    \
                                                                       \
        WPP_DEFINE_BIT(MYDRIVER_ALL_INFO)                              \
        WPP_DEFINE_BIT(TRACE_DRIVER)                                   \
        WPP_DEFINE_BIT(TRACE_DEVICE)                                   \
        WPP_DEFINE_BIT(TRACE_QUEUE)                                    \
        )                             

#define WPP_FLAG_LEVEL_LOGGER(flag, level)                             \
    WPP_LEVEL_LOGGER(flag)

#define WPP_FLAG_LEVEL_ENABLED(flag, level)                            \
    (WPP_LEVEL_ENABLED(flag) &&                                        \
     WPP_CONTROL(WPP_BIT_ ## flag).Level >= level)

#define WPP_LEVEL_FLAGS_LOGGER(lvl,flags) \
           WPP_LEVEL_LOGGER(flags)

#define WPP_LEVEL_FLAGS_ENABLED(lvl, flags) \
           (WPP_LEVEL_ENABLED(flags) && WPP_CONTROL(WPP_BIT_ ## flags).Level >= lvl)

Internal.h の次の行で、キューコールバックオブジェクトのクライアントドライバー実装クラスを宣言します。テンプレートによって生成された他のプロジェクトファイルも含まれます。実装およびプロジェクトのヘッダーファイルについては、このトピックで後ほど説明します。

// Forward definition of queue.

typedef class CMyIoQueue *PCMyIoQueue;

// Include the type specific headers.

#include "Driver.h"
#include "Device.h"
#include "IoQueue.h"

クライアントドライバーがインストールされると、Windows はクライアントドライバーとフレームワークをホストプロセスのインスタンスに読み込みます。こここから、フレームワークはクライアントドライバーをロードして初期化します。このフレームワークは、次のタスクを実行します。

クライアントドライバーを表すドライバーオブジェクトをフレームワークに作成します。
クラスファクトリから IDriverEntry インターフェイスポインターを要求します。
フレームワークにデバイスオブジェクトを作成します。
PnP マネージャーがデバイスを起動した後、デバイスオブジェクトを初期化します。

ドライバーの読み込みと初期化中に、いくつかのイベントが発生し、フレームワークによってクライアントドライバーがイベントの処理に参加できるようになります。クライアントドライバー側では、ドライバーは次のタスクを実行します。

フレームワークがドライバーへの参照を取得できるように、クライアントドライバーモジュールから DllGetClassObject 関数を実装し、エクスポートします。
IDriverEntry インターフェイスを実装するコールバッククラスを提供します。
IPnpCallbackXxx インターフェイスを実装するコールバッククラスを提供します。
デバイスオブジェクトへの参照を取得し、クライアントドライバーの要件に従って構成します。

ドライバーコールバックのソースコード

フレームワークは、Windows によって読み込まれたクライアントドライバーのインスタンスを表すドライバーオブジェクトを作成します。クライアントドライバーは、ドライバーをフレームワークに登録するドライバーコールバックを少なくとも 1 つ提供します。

ドライバーコールバックの完全なソースコードは、Driver.h と Driver.c にあります。

クライアントドライバーは、IUnknown インターフェイスと IDriverEntry インターフェイスを実装するドライバーコールバッククラスを定義する必要があります。ヘッダーファイル Driver.h は、ドライバーコールバックを定義する CMyDriver というクラスを宣言します。

EXTERN_C const CLSID CLSID_Driver;

class CMyDriver :
    public CComObjectRootEx<CComMultiThreadModel>,
    public CComCoClass<CMyDriver, &CLSID_Driver>,
    public IDriverEntry
{
public:

    CMyDriver()
    {
    }

    DECLARE_NO_REGISTRY()

    DECLARE_NOT_AGGREGATABLE(CMyDriver)

    BEGIN_COM_MAP(CMyDriver)
        COM_INTERFACE_ENTRY(IDriverEntry)
    END_COM_MAP()

public:

    // IDriverEntry methods

    virtual
    HRESULT
    STDMETHODCALLTYPE
    OnInitialize(
        __in IWDFDriver *FxWdfDriver
        )
    {
        UNREFERENCED_PARAMETER(FxWdfDriver);
        return S_OK;
    }

    virtual
    HRESULT
    STDMETHODCALLTYPE
    OnDeviceAdd(
        __in IWDFDriver *FxWdfDriver,
        __in IWDFDeviceInitialize *FxDeviceInit
        );

    virtual
    VOID
    STDMETHODCALLTYPE
    OnDeinitialize(
        __in IWDFDriver *FxWdfDriver
        )
    {
        UNREFERENCED_PARAMETER(FxWdfDriver);
        return;
    }

};

OBJECT_ENTRY_AUTO(CLSID_Driver, CMyDriver)

ドライバーコールバックは COM クラスである必要があります。つまり、IUnknown および関連するメソッドを実装する必要があります。テンプレートコードでは、ATL クラス CComObjectRootEx と CComCoClass に IUnknown メソッドが含まれています。

Windows がホストプロセスをインスタンス化すると、フレームワークによってドライバーオブジェクトが作成されます。これを行うために、フレームワークはドライバーコールバッククラスのインスタンスを作成し、DllGetClassObject のドライバー実装を呼び出し (「ドライバーエントリのソースコード」セクションで説明) し、クライアントドライバーの IDriverEntry インターフェイスポインターを取得します。この呼び出しにより、ドライバーコールバックオブジェクトがフレームワークドライバーオブジェクトに登録されます。登録が成功すると、特定のドライバー固有のイベントが発生すると、フレームワークはクライアントドライバーの実装を呼び出します。フレームワークが呼び出す最初のメソッドは、IDriverEntry::OnInitialize メソッドです。クライアントドライバーの IDriverEntry::OnInitialize の実装では、クライアントドライバーはグローバルドライバーリソースを割り当てることができます。これらのリソースは、クライアントドライバーのアンロードを準備する直前にフレームワークによって呼び出される IDriverEntry::OnDeinitialize で解放する必要があります。テンプレートコードは、OnInitialize メソッドと OnDeinitialize メソッドの最小限の実装を提供します。

IDriverEntry の最も重要なメソッドは、IDriverEntry::OnDeviceAdd です。フレームワークがフレームワークデバイスオブジェクトを作成する前に (次のセクションで説明します)、ドライバーの IDriverEntry::OnDeviceAdd 実装を呼び出します。メソッドを呼び出すと、フレームワークはドライバーオブジェクトと IWDFDeviceInitialize ポインターに IWDFDriver ポインターを渡します。クライアントドライバーは、IWDFDeviceInitialize メソッドを呼び出して、特定の構成オプションを指定できます。

通常、クライアントドライバーは、IDriverEntry::OnDeviceAdd 実装で次のタスクを実行します。

作成するデバイスオブジェクトの構成情報を指定します。
ドライバーのデバイスコールバッククラスをインスタンス化します。
フレームワークデバイスオブジェクトを作成し、そのデバイスコールバックオブジェクトをフレームワークに登録します。
フレームワークデバイスオブジェクトを初期化します。
クライアントドライバーのデバイスインターフェイス GUID を登録します。

テンプレートコードでは、IDriverEntry::OnDeviceAdd は、デバイスコールバッククラスで定義されている静的メソッド CMyDevice::CreateInstanceAndInitialize を呼び出します。静的メソッドは、最初にクライアントドライバーのデバイスコールバッククラスをインスタンス化し、フレームワークデバイスオブジェクトを作成します。また、デバイスコールバッククラスは、前の一覧でメンションメインタスクを再実行する Configure という名前のパブリックメソッドも定義します。デバイスコールバッククラスの実装については、次のセクションで説明します。次のコード例は、テンプレートコードの IDriverEntry::OnDeviceAdd 実装を示しています。

HRESULT
CMyDriver::OnDeviceAdd(
    __in IWDFDriver *FxWdfDriver,
    __in IWDFDeviceInitialize *FxDeviceInit
    )
{
    HRESULT hr = S_OK;
    CMyDevice *device = NULL;

    hr = CMyDevice::CreateInstanceAndInitialize(FxWdfDriver,
                                                FxDeviceInit,
                                                &device);

    if (SUCCEEDED(hr))
    {
        hr = device->Configure();
    }

    return hr;
}

次のコード例は、Device.h でのデバイスクラスの宣言を示しています。

class CMyDevice :
    public CComObjectRootEx<CComMultiThreadModel>,
    public IPnpCallbackHardware
{

public:

    DECLARE_NOT_AGGREGATABLE(CMyDevice)

    BEGIN_COM_MAP(CMyDevice)
        COM_INTERFACE_ENTRY(IPnpCallbackHardware)
    END_COM_MAP()

    CMyDevice() :
        m_FxDevice(NULL),
        m_IoQueue(NULL),
        m_FxUsbDevice(NULL)
    {
    }

    ~CMyDevice()
    {
    }

private:

    IWDFDevice *            m_FxDevice;

    CMyIoQueue *            m_IoQueue;

    IWDFUsbTargetDevice *   m_FxUsbDevice;

private:

    HRESULT
    Initialize(
        __in IWDFDriver *FxDriver,
        __in IWDFDeviceInitialize *FxDeviceInit
        );

public:

    static
    HRESULT
    CreateInstanceAndInitialize(
        __in IWDFDriver *FxDriver,
        __in IWDFDeviceInitialize *FxDeviceInit,
        __out CMyDevice **Device
        );

    HRESULT
    Configure(
        VOID
        );
public:

    // IPnpCallbackHardware methods

    virtual
    HRESULT
    STDMETHODCALLTYPE
    OnPrepareHardware(
            __in IWDFDevice *FxDevice
            );

    virtual
    HRESULT
    STDMETHODCALLTYPE
    OnReleaseHardware(
        __in IWDFDevice *FxDevice
        );

};

デバイスコールバックのソースコード

フレームワークデバイスオブジェクトは、クライアントドライバーのデバイススタックに読み込まれるデバイスオブジェクトを表すフレームワーククラスのインスタンスです。デバイスオブジェクトの機能の詳細については、「デバイスノードとデバイススタック」を参照してください。

デバイスオブジェクトの完全なソースコードは、Device.h と Device.c にあります。

フレームワークデバイスクラスは、IWDFDevice インターフェイスを実装します。クライアントドライバーは、ドライバーの IDriverEntry::OnDeviceAdd の実装でそのクラスのインスタンスを作成する役割を担います。オブジェクトが作成されると、クライアントドライバーは新しいオブジェクトへの IWDFDevice ポインターを取得し、そのインターフェイスのメソッドを呼び出してデバイスオブジェクトの操作を管理します。

IDriverEntry::OnDeviceAdd 実装

前のセクションでは、クライアントドライバーが IDriverEntry::OnDeviceAdd で実行するタスクについて簡単に説明しました。これらのタスクの詳細については、以下を参照してください。クライアントドライバー:

作成するデバイスオブジェクトの構成情報を指定します。

IDriverEntry::OnDeviceAdd メソッドのクライアントドライバーの実装に対するフレームワーク呼び出しでは、フレームワークは IWDFDeviceInitialize ポインターを渡します。クライアントドライバーは、このポインターを使用して、作成するデバイスオブジェクトの構成情報を指定します。たとえば、クライアントドライバーは、クライアントドライバーがフィルターであるかファンクションドライバーであるかを指定します。クライアントドライバーをフィルタードライバーとして識別するために、IWDFDeviceInitialize::SetFilter を呼び出します。その場合、フレームワークはフィルターデバイスオブジェクト (FiDO) を作成します。それ以外の場合は、関数デバイスオブジェクト (FDO) が作成されます。設定できるもう 1 つのオプションは、IWDFDeviceInitialize::SetLockingConstraint を呼び出すことによる同期モードです。
IWDFDeviceInitialize インターフェイスポインター、デバイスコールバックオブジェクトの IUnknown 参照、およびポインターからポインターへのポインター IWDFDevice 変数を渡すことによって、IWDFDriver::CreateDevice メソッドを呼び出します。

IWDFDriver::CreateDevice 呼び出しが成功した場合:
- フレームワークは、デバイスオブジェクトを作成します。
- フレームワークは、デバイスコールバックをフレームワークに登録します。
  
  デバイスコールバックがフレームワークデバイスオブジェクトとペアになると、フレームワークとクライアントドライバーは、PnP 状態や電源状態の変化などの特定のイベントを処理します。たとえば、PnP マネージャーがデバイスを起動すると、フレームワークに通知されます。その後、フレームワークはデバイスコールバックの IPnpCallbackHardware::OnPrepareHardware 実装を呼び出します。すべてのクライアントドライバーは、少なくとも 1 つのデバイスコールバックオブジェクトを登録する必要があります。
- クライアントドライバーは、IWDFDevice 変数の新しいデバイスオブジェクトのアドレスを受け取ります。フレームワークデバイスオブジェクトへのポインターを受信すると、クライアントドライバーは、I/O フローのキューの設定やデバイスインターフェイス GUID の登録などの初期化タスクを続行できます。
IWDFDevice::CreateDeviceInterface を呼び出して、クライアントドライバーのデバイスインターフェイス GUID を登録します。アプリケーションでは、GUID を使用してクライアントドライバーに要求を送信できます。 GUID 定数は Internal.h で宣言されています。
デバイスとの間の I/O 転送のキューを初期化します。

テンプレートコードは、構成情報を指定してデバイスオブジェクトを作成するヘルパーメソッド Initialize を定義します。

次のコード例は、Initialize の実装を示しています。

HRESULT
CMyDevice::Initialize(
    __in IWDFDriver           * FxDriver,
    __in IWDFDeviceInitialize * FxDeviceInit
    )
{
    IWDFDevice *fxDevice = NULL;
    HRESULT hr = S_OK;
    IUnknown *unknown = NULL;

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Entry");

    FxDeviceInit->SetLockingConstraint(None);

    FxDeviceInit->SetPowerPolicyOwnership(TRUE);

    hr = this->QueryInterface(__uuidof(IUnknown), (void **)&unknown);
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to get IUnknown %!hresult!",
                    hr);
        goto Exit;
    }

    hr = FxDriver->CreateDevice(FxDeviceInit, unknown, &fxDevice);
    DriverSafeRelease(unknown);
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to create a framework device %!hresult!",
                    hr);
        goto Exit;
    }

     m_FxDevice = fxDevice;

     DriverSafeRelease(fxDevice);

Exit:

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Exit");

    return hr;
}

前述のコード例では、クライアントドライバーがデバイスオブジェクトを作成し、そのデバイスコールバックを登録します。デバイスオブジェクトを作成する前に、ドライバーは IWDFDeviceInitialize インターフェイスポインターでメソッドを呼び出すことによって、その構成設定を指定します。これは、クライアントドライバーの IDriverEntry::OnDeviceAdd メソッドへの以前の呼び出しでフレームワークによって渡されたのと同じポインターです。

クライアントドライバーは、デバイスオブジェクトの電源ポリシーの所有者になることを指定します。クライアントドライバーは、電源ポリシーの所有者として、システムの電源状態が変化したときにデバイスが移行する適切な電源状態を決定します。ドライバーは、電源状態を遷移させるために、関連する要求をデバイスに送信する責任もあります。既定では、UMDF ベースのクライアントドライバーは電源ポリシーの所有者ではありません。フレームワークはすべての電源状態の遷移を処理します。フレームワークは、システムがスリープ状態になったときにデバイスを D3 に自動的に送信し、逆にシステムが S0 の動作状態になったときにデバイスを D0 に戻します。詳細については、「UMDF の電源ポリシーの所有権」を参照してください。

もう 1 つの構成オプションは、クライアントドライバーがデバイスのフィルタードライバーであるかファンクションドライバーであるかを指定することです。コード例では、クライアントドライバーがその設定を明示的に指定していないことに注意してください。つまり、クライアントドライバーはファンクションドライバーであり、フレームワークはデバイススタックに FDO を作成する必要があります。クライアントドライバーをフィルタードライバーにする場合、ドライバーは IWDFDeviceInitialize::SetFilter メソッドを呼び出す必要があります。その場合、フレームワークはデバイススタックに FiDO を作成します。

クライアントドライバーは、クライアントドライバーのコールバックに対するフレームワークの呼び出しが同期されないことも指定します。クライアントドライバーは、すべての同期タスクを処理します。この基本設定を指定するために、クライアントドライバーは IWDFDeviceInitialize::SetLockingConstraint メソッドを呼び出します。

次に、クライアントドライバーは、IUnknown::QueryInterface を呼び出して、デバイスコールバッククラスへの IUnknown ポインターを取得します。その後、クライアントドライバーは IWDFDriver::CreateDevice を呼び出します。これによってフレームワークデバイスオブジェクトが作成され、IUnknown ポインターを使用してクライアントドライバーのデバイスコールバックが登録されます。

クライアントドライバーは、デバイスコールバッククラスのプライベートデータメンバーにデバイスオブジェクトのアドレス (IWDFDriver::CreateDevice 呼び出しを通じて受信) を格納し、DriverSafeRelease (Internal.h で定義されたインライン関数) を呼び出してその参照を解放します。これは、デバイスオブジェクトの有効期間がフレームワークによって追跡されるためです。そのため、クライアントドライバーは、デバイスオブジェクトの追加の参照カウントを保持する必要はありません。

テンプレートコードは、デバイスインターフェイス GUID を登録し、キューを設定するパブリックメソッド Configure を定義します。次のコード例は、デバイスコールバッククラス CMyDevice の Configure メソッドの定義を示しています。構成は、フレームワークデバイスオブジェクトの作成後に IDriverEntry::OnDeviceAdd によって呼び出されます。

CMyDevice::Configure(
    VOID
    )
{

    HRESULT hr = S_OK;

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Entry");

     hr = CMyIoQueue::CreateInstanceAndInitialize(m_FxDevice, this, &m_IoQueue);
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to create and initialize queue %!hresult!",
                    hr);
        goto Exit;
    }

    hr = m_IoQueue->Configure();
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to configure queue %!hresult!",
                    hr);
        goto Exit;
    } 

    hr = m_FxDevice->CreateDeviceInterface(&GUID_DEVINTERFACE_MyUSBDriver_UMDF_,NULL);
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to create device interface %!hresult!",
                    hr);
        goto Exit;
    }

Exit:

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Exit");

    return hr;
}

前述のコード例では、クライアントドライバーは、I/O フローのキューの初期化とデバイスインターフェイス GUID の登録という 2 つの主要なタスクを実行します。

キューは CMyIoQueue クラスで作成および構成されます。最初のタスクは、CreateInstanceAndInitialize という名前の静的メソッドを呼び出して、そのクラスをインスタンス化することです。クライアントドライバーは、キューを初期化する構成を呼び出します。 CreateInstanceAndInitialize と Configure は CMyIoQueue で宣言されます。これについては、このトピックで後ほど説明します。

また、クライアントドライバーは IWDFDevice::CreateDeviceInterface を呼び出して、クライアントドライバーのデバイスインターフェイス GUID を登録します。アプリケーションでは、GUID を使用してクライアントドライバーに要求を送信できます。 GUID 定数は Internal.h で宣言されています。

IPnpCallbackHardware の実装と USB 固有のタスク

次に、Device.cpp の IPnpCallbackHardware インターフェイスの実装を見てみましょう。

すべてのデバイスコールバッククラスは、IPnpCallbackHardware インターフェイスを実装する必要があります。このインターフェイスには、IPnpCallbackHardware::OnPrepareHardware および IPnpCallbackHardware::OnReleaseHardware の 2 つのメソッドがあります。フレームワークは、PnP マネージャーがデバイスを起動したときとデバイスを削除したときの 2 つのイベントに応答して、これらのメソッドを呼び出します。デバイスが起動されると、ハードウェアへの通信は確立されますが、デバイスは動作状態 (D0) に入っていません。そのため、IPnpCallbackHardware::OnPrepareHardware では、クライアントドライバーは、ハードウェアからデバイス情報を取得し、リソースを割り当て、ドライバーの有効期間中に必要なフレームワークオブジェクトを初期化できます。 PnP マネージャーがデバイスを削除すると、ドライバーはシステムからアンロードされます。フレームワークは、クライアントドライバーの IPnpCallbackHardware::OnReleaseHardware 実装を呼び出します。この実装では、ドライバーはこれらのリソースとフレームワークオブジェクトを解放できます。

PnP マネージャーは、PnP 状態の変更に起因する他の種類のイベントを生成できます。フレームワークは、これらのイベントの既定の処理を提供します。クライアントドライバーは、これらのイベントの処理に参加することを選択できます。 USB デバイスがホストから切り離されるシナリオを考えてみましょう。 PnP マネージャーは、そのイベントを認識し、フレームワークに通知します。クライアントドライバーがイベントに応答して追加のタスクを実行する場合、ドライバーは IPnpCallback インターフェイスと関連する IPnpCallback::OnSurpriseRemoval メソッドをデバイスコールバッククラスに実装する必要があります。それ以外の場合、フレームワークはイベントの既定の処理を続行します。

USB クライアントドライバーは、データ転送のための I/O 要求を送信する前に、サポートされているインターフェイス、代替設定、およびエンドポイントに関する情報を取得し、構成する必要があります。 UMDF は、クライアントドライバーの構成タスクの多くを簡素化する特殊な I/O ターゲットオブジェクトを提供します。 USB デバイスを構成するには、クライアントドライバーには、PnP マネージャーがデバイスを起動した後にのみ使用できるデバイス情報が必要です。

このテンプレートコードは、IPnpCallbackHardware::OnPrepareHardware メソッドでこれらのオブジェクトを作成します。

通常、クライアントドライバーは、(デバイスの設計に応じて) 次の構成タスクの 1 つ以上を実行します。

インターフェイスの数など、現在の構成に関する情報を取得します。フレームワークは、USB デバイスの最初の構成を選択します。複数構成デバイスの場合、クライアントドライバーは別の構成を選択できません。
エンドポイントの数など、インターフェイスに関する情報を取得します。
インターフェイスが複数の設定をサポートしている場合は、各インターフェイス内の代替設定を変更します。既定では、フレームワークは USB デバイスの最初の構成で各インターフェイスの最初の代替設定を選択します。クライアントドライバーは、代替設定を選択できます。
各インターフェイス内のエンドポイントに関する情報を取得します。

これらのタスクを実行するために、クライアントドライバーは、WDF によって提供されるこれらの種類の特殊な USB I/O ターゲットオブジェクトを使用できます。

USB I/O ターゲットオブジェクト	説明	UMDF インターフェイス
ターゲットデバイスオブジェクト	USB デバイスを表し、デバイス記述子を取得し、デバイスに制御要求を送信するためのメソッドを提供します。	IWDFUsbTargetDevice
ターゲットインターフェイスオブジェクト	個別のインターフェイスを表し、クライアントドライバーが代替設定を選択し、設定に関する情報を取得するために呼び出すことができるメソッドを提供します。	IWDFUsbInterface
ターゲットパイプオブジェクト	インターフェイスの現在の代替設定で構成されているエンドポイントの個別のパイプを表します。 USB バスドライバーは、選択された構成内の各インターフェイスを選択し、インターフェイス内の各エンドポイントへのコミュニケーションチャネルを設定します。 USB の用語では、その通信チャネルはパイプと呼ばれます。	IWDFUsbTargetPipe

次のコード例は、IPnpCallbackHardware::OnPrepareHardware の実装を示しています。

HRESULT
CMyDevice::OnPrepareHardware(
    __in IWDFDevice * /* FxDevice */
    )
{
    HRESULT hr;
    IWDFUsbTargetFactory *usbFactory = NULL;
    IWDFUsbTargetDevice *usbDevice = NULL;

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Entry");

    hr = m_FxDevice->QueryInterface(IID_PPV_ARGS(&usbFactory));

    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to get USB target factory %!hresult!",
                    hr);
        goto Exit;
    }

    hr = usbFactory->CreateUsbTargetDevice(&usbDevice);

    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_DEVICE,
                    "%!FUNC! Failed to create USB target device %!hresult!",
                    hr);

        goto Exit;
    }

     m_FxUsbDevice = usbDevice;

Exit:

    DriverSafeRelease(usbDevice);

    DriverSafeRelease(usbFactory);

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Exit");

    return hr;
}

フレームワークの USB I/O ターゲットオブジェクトを使用するには、クライアントドライバーは最初に USB ターゲットデバイスオブジェクトを作成する必要があります。フレームワークオブジェクトモデルでは、USB ターゲットデバイスオブジェクトは、USB デバイスを表すデバイスオブジェクトの子です。 USB ターゲットデバイスオブジェクトはフレームワークによって実装され、構成の選択など、USB デバイスのすべてのデバイスレベルのタスクを実行します。

前のコード例では、クライアントドライバーはフレームワークデバイスオブジェクトを照会し、USB ターゲットデバイスオブジェクトを作成するクラスファクトリへの IWDFUsbTargetFactory ポインターを取得します。このポインターを使用して、クライアントドライバーは IWDFUsbTargetDevice::CreateUsbTargetDevice メソッドを呼び出します。このメソッドは、USB ターゲットデバイスオブジェクトを作成し、IWDFUsbTargetDevice インターフェイスへのポインターを返します。このメソッドでは、既定の (最初の) 構成と、その構成内の各インターフェイスの代替設定 0 も選択します。

テンプレートコードは、USB ターゲットデバイスオブジェクト (IWDFDriver::CreateDevice 呼び出しを通じて受信) のアドレスをデバイスコールバッククラスのプライベートデータメンバーに格納し、DriverSafeRelease を呼び出してその参照を解放します。 USB ターゲットデバイスオブジェクトの参照カウントは、フレームワークによってメインされます。デバイスオブジェクトが有効である限り、オブジェクトは有効です。クライアントドライバーは、IPnpCallbackHardware::OnReleaseHardware で参照を解放する必要があります。

クライアントドライバーが USB ターゲットデバイスオブジェクトを作成した後、ドライバーは IWDFUsbTargetDevice メソッドを呼び出して次のタスクを実行します。

デバイス、構成、インターフェイス記述子、およびその他の情報 (デバイス速度など) を取得します。
I/O 制御要求を書式設定して既定のエンドポイントに送信します。
USB デバイス全体の電源ポリシーを設定します。

詳細については、「UMDF での USB デバイスの操作」を参照してください。次のコード例は、IPnpCallbackHardware::OnReleaseHardware の実装を示しています。

HRESULT
CMyDevice::OnReleaseHardware(
    __in IWDFDevice * /* FxDevice */
    )
{
    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Entry");

    if (m_FxUsbDevice != NULL) {

        m_FxUsbDevice->DeleteWdfObject();
        m_FxUsbDevice = NULL;
    }

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_DEVICE, "%!FUNC! Exit");

    return S_OK;
}

キューのソースコード

フレームワークキューオブジェクトは、特定のフレームワークデバイスオブジェクトの I/O キューを表します。キューオブジェクトの完全なソースコードは、IoQueue.h と IoQueue.c にあります。

IoQueue.h

ヘッダーファイル IoQueue.h は、キューコールバッククラスを宣言します。

class CMyIoQueue :
    public CComObjectRootEx<CComMultiThreadModel>,
    public IQueueCallbackDeviceIoControl
{

public:

    DECLARE_NOT_AGGREGATABLE(CMyIoQueue)

    BEGIN_COM_MAP(CMyIoQueue)
        COM_INTERFACE_ENTRY(IQueueCallbackDeviceIoControl)
    END_COM_MAP()

    CMyIoQueue() : 
        m_FxQueue(NULL),
        m_Device(NULL)
    {
    }

    ~CMyIoQueue()
    {
        // empty
    }

    HRESULT
    Initialize(
        __in IWDFDevice *FxDevice,
        __in CMyDevice *MyDevice
        );

    static 
    HRESULT 
    CreateInstanceAndInitialize( 
        __in IWDFDevice *FxDevice,
        __in CMyDevice *MyDevice,
        __out CMyIoQueue**    Queue
        );

    HRESULT
    Configure(
        VOID
        )
    {
        return S_OK;
    }


    // IQueueCallbackDeviceIoControl

    virtual
    VOID
    STDMETHODCALLTYPE
    OnDeviceIoControl( 
        __in IWDFIoQueue *pWdfQueue,
        __in IWDFIoRequest *pWdfRequest,
        __in ULONG ControlCode,
        __in SIZE_T InputBufferSizeInBytes,
        __in SIZE_T OutputBufferSizeInBytes
        );

private:

    IWDFIoQueue *               m_FxQueue;

    CMyDevice *                 m_Device;

};

前のコード例では、クライアントドライバーはキューコールバッククラスを宣言しています。インスタンス化されると、オブジェクトは、要求がクライアントドライバーにディスパッチされる方法を処理するフレームワークキューオブジェクトと連携します。このクラスは、フレームワークキューオブジェクトを作成および初期化する 2 つのメソッドを定義します。静的メソッド CreateInstanceAndInitialize はキューコールバッククラスをインスタンス化し、フレームワークキューオブジェクトを作成して初期化する Initialize メソッドを呼び出します。キューオブジェクトのディスパッチオプションも指定します。

HRESULT 
CMyIoQueue::CreateInstanceAndInitialize(
    __in IWDFDevice *FxDevice,
    __in CMyDevice *MyDevice,
    __out CMyIoQueue** Queue
    )
{

    CComObject<CMyIoQueue> *pMyQueue = NULL;
    HRESULT hr = S_OK;

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Entry");

    hr = CComObject<CMyIoQueue>::CreateInstance( &pMyQueue );
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_QUEUE,
                    "%!FUNC! Failed to create instance %!hresult!",
                    hr);
        goto Exit;
    }

    hr = pMyQueue->Initialize(FxDevice, MyDevice);
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_QUEUE,
                    "%!FUNC! Failed to initialize %!hresult!",
                    hr);
        goto Exit;
    }

    *Queue = pMyQueue;

Exit:

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Exit");

    return hr;
}

次のコード例は、Initialize メソッドの実装を示しています。

HRESULT
CMyIoQueue::Initialize(
    __in IWDFDevice *FxDevice,
    __in CMyDevice *MyDevice
    )
{
    IWDFIoQueue *fxQueue = NULL;
    HRESULT hr = S_OK;
    IUnknown *unknown = NULL;

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Entry");

    assert(FxDevice != NULL);
    assert(MyDevice != NULL);

    hr = this->QueryInterface(__uuidof(IUnknown), (void **)&unknown);
    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR,
                    TRACE_QUEUE,
                    "%!FUNC! Failed to query IUnknown interface %!hresult!",
                    hr);
        goto Exit;
    }

    hr = FxDevice->CreateIoQueue(unknown,
                                 FALSE,     // Default Queue?
                                 WdfIoQueueDispatchParallel,  // Dispatch type
                                 TRUE,     // Power managed?
                                 FALSE,     // Allow zero-length requests?
                                 &fxQueue); // I/O queue
    DriverSafeRelease(unknown);

    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR, 
                   TRACE_QUEUE, 
                   "%!FUNC! Failed to create framework queue.");
        goto Exit;
    }

    hr = FxDevice->ConfigureRequestDispatching(fxQueue,
                                               WdfRequestDeviceIoControl,
                                               TRUE);

    if (FAILED(hr))
    {
        TraceEvents(TRACE_LEVEL_ERROR, 
                   TRACE_QUEUE, 
                   "%!FUNC! Failed to configure request dispatching %!hresult!.",
                   hr);
        goto Exit;
    }

    m_FxQueue = fxQueue;
    m_Device= MyDevice;

Exit:

    DriverSafeRelease(fxQueue);

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Exit");

    return hr;
}

前述のコード例では、クライアントドライバーがフレームワークキューオブジェクトを作成します。フレームワークは、クライアントドライバーへの要求フローを処理するためのキューオブジェクトを提供します。

オブジェクトを作成するために、クライアントドライバーは IWDFDriver::CreateDevice への以前の呼び出しで取得した IWDFDevice 参照で IWDFDevice::CreateIoQueue を呼び出します。

IWDFDevice::CreateIoQueue 呼び出しでは、フレームワークがキューを作成する前に、クライアントドライバーによって特定の構成オプションが指定されます。これらのオプションは、キューが電源管理されるかどうか、長さ 0 の要求を許可するかどうか、およびドライバーの既定のキューとして機能するかどうかを決定します。クライアントドライバーは、次の一連の情報を提供します。

そのキューコールバッククラスへの参照

キューコールバッククラスへの IUnknown ポインターを指定します。これにより、フレームワークキューオブジェクトとクライアントドライバーのキューコールバックオブジェクトの間にパートナーシップが作成されます。 I/O マネージャーは、アプリケーションから新しい要求を受信すると、フレームワークに通知します。その後、フレームワークは IUnknown ポインターを使用して、キューコールバックオブジェクトによって公開されるパブリックメソッドを呼び出します。
既定またはセカンダリキュー

キューは、既定のキューまたはセカンダリキューである必要があります。フレームワークキューオブジェクトが既定のキューとして機能する場合、すべての要求がキューに追加されます。セカンダリキューは、特定の種類の要求専用です。クライアントドライバーがセカンダリキューを要求する場合、ドライバーは IWDFDevice::ConfigureRequestDispatching メソッドも呼び出して、フレームワークが指定されたキューに配置する必要がある要求の種類を示す必要があります。テンプレートコードでは、クライアントドライバーは bDefaultQueue パラメーターに FALSE を渡します。これにより、既定のキューではなく、セカンダリキューを作成するようにメソッドに指示します。後で IWDFDevice::ConfigureRequestDispatching を呼び出して、キューにデバイス I/O 制御要求のみが必要であることを示します (このセクションのコード例を参照)。
ディスパッチの種類

キューオブジェクトのディスパッチの種類は、フレームワークがクライアントドライバーに要求を配信する方法を決定します。配信メカニズムは、順次、並列、またはクライアントドライバーによって定義されたカスタムメカニズムによって行うことができます。順次キューの場合、クライアントドライバーが前の要求を完了するまで、要求は配信されません。並列ディスパッチモードでは、フレームワークは I/O マネージャーから要求が到着すると、すぐに要求を転送します。これは、クライアントドライバーが別の要求を処理している間に要求を受信できることを意味します。カスタムメカニズムでは、ドライバーが次の要求を処理する準備ができたら、クライアントはフレームワークキューオブジェクトから次の要求を手動で引き出します。テンプレートコードでは、クライアントドライバーは並列ディスパッチモードを要求します。
電源管理キュー

フレームワークキューオブジェクトは、PnP およびデバイスの電源状態と同期する必要があります。デバイスが作業状態でない場合、フレームワークキューオブジェクトは、すべての要求のディスパッチを停止します。デバイスが作業状態になると、キューオブジェクトはディスパッチを再開します。電源管理キューでは、同期はフレームワークによって実行されます。それ以外の場合は、クライアントドライブがそのタスクを処理する必要があります。テンプレートコードでは、クライアントは電源管理キューを要求します。
許可される長さ 0 の要求

クライアントドライバーは、I/O 要求をキューに入れるのではなく、長さ 0 のバッファーで完了するようにフレームワークに指示できます。テンプレートコードでは、クライアントはそのような要求を完了するようにフレームワークに要求します。

1 つのフレームワークキューオブジェクトは、読み取り、書き込み、デバイス I/O 制御など、いくつかの種類の要求を処理できます。テンプレートコードに基づくクライアントドライバーは、デバイス I/O 制御要求のみを処理できます。そのため、クライアントドライバーのキューコールバッククラスは、IQueueCallbackDeviceIoControl インターフェイスとその IQueueCallbackDeviceIoControl::OnDeviceIoControl メソッドを実装します。これにより、フレームワークがデバイス I/O コントロール要求を処理するときに、フレームワークがクライアントドライバーの IQueueCallbackDeviceIoControl::OnDeviceIoControl の実装を呼び出すことができます。

その他の種類の要求の場合、クライアントドライバーは対応する IQueueCallbackXxx インターフェイスを実装する必要があります。たとえば、クライアントドライバーが読み取り要求を処理する場合、キューコールバッククラスは IQueueCallbackRead インターフェイスとその IQueueCallbackRead::OnRead メソッドを実装する必要があります。要求とコールバックインターフェイスの種類については、「I/O キューイベントコールバック関数」を参照してください。

次のコード例は、IQueueCallbackDeviceIoControl::OnDeviceIoControl の実装を示しています。

VOID
STDMETHODCALLTYPE
CMyIoQueue::OnDeviceIoControl(
    __in IWDFIoQueue *FxQueue,
    __in IWDFIoRequest *FxRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    UNREFERENCED_PARAMETER(FxQueue);
    UNREFERENCED_PARAMETER(ControlCode);
    UNREFERENCED_PARAMETER(InputBufferSizeInBytes);
    UNREFERENCED_PARAMETER(OutputBufferSizeInBytes);

    HRESULT hr = S_OK;

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Entry");

    if (m_Device == NULL) {
        // We don't have pointer to device object
        TraceEvents(TRACE_LEVEL_ERROR, 
                   TRACE_QUEUE, 
                   "%!FUNC!NULL pointer to device object.");
        hr = E_POINTER;
        goto Exit;
    }

    //
    // Process the IOCTLs
    //

Exit:

    FxRequest->Complete(hr);

    TraceEvents(TRACE_LEVEL_INFORMATION, TRACE_QUEUE, "%!FUNC! Exit");

    return;

}

キューメカニズムのしくみを見てみましょう。 USB デバイスと通信するために、アプリケーションは最初にデバイスにハンドルを開き、特定のコントロールコードで DeviceIoControl 関数を呼び出して、デバイス I/O 制御要求を送信します。制御コードのタイプに応じて、アプリケーションはその呼び出しで入力バッファーと出力バッファーを指定できます。呼び出しは最終的に I/O マネージャーによって受信され、フレームワークに通知されます。フレームワークはフレームワーク要求オブジェクトを作成し、フレームワークキューオブジェクトに追加します。テンプレートコードでは、キューオブジェクトが WdfIoQueueDispatchParallel フラグを使用して作成されているため、要求がキューに追加されるとすぐにコールバックが呼び出されます。

フレームワークは、クライアントドライバーのイベントコールバックを呼び出すと、アプリケーションによって送信された要求 (およびその入力バッファーと出力バッファー) を保持するフレームワーク要求オブジェクトにハンドルを渡します。さらに、その要求を含むフレームワークキューオブジェクトにハンドルを送信します。イベントコールバックでは、クライアントドライバーは必要に応じて要求を処理します。テンプレートコードは、要求を完了するだけです。クライアントドライバーは、より複雑なタスクを実行できます。たとえば、アプリケーションがイベントコールバックで特定のデバイス情報を要求した場合、クライアントドライバーは USB 制御要求を作成し、それを USB ドライバースタックに送信して、要求されたデバイス情報を取得できます。 USB コントロールの要求については、「USB コントロール転送」で説明します。

ドライバーエントリのソースコード

テンプレートコードでは、ドライバーエントリが Dllsup.cpp に実装されています。

Dllsup.cpp

include セクションの後に、クライアントドライバーの GUID 定数が宣言されます。その GUID は、ドライバーのインストールファイル (INF) の GUID と一致する必要があります。

const CLSID CLSID_Driver =
{0x079e211c,0x8a82,0x4c16,{0x96,0xe2,0x2d,0x28,0xcf,0x23,0xb7,0xff}};

次のコードブロックは、クライアントドライバーのクラスファクトリを宣言します。

class CMyDriverModule :
    public CAtlDllModuleT< CMyDriverModule >
{
};

CMyDriverModule _AtlModule;

テンプレートコードでは、ATL サポートを使用して複雑な COM コードをカプセル化します。クラスファクトリは、クライアントドライバーの作成に必要なすべてのコードを含むテンプレートクラス CAtlDllModuleT を継承します。

次のコードスニペットは、DllMain の実装を示しています

extern "C"
BOOL
WINAPI
DllMain(
    HINSTANCE hInstance,
    DWORD dwReason,
    LPVOID lpReserved
    )
{
    if (dwReason == DLL_PROCESS_ATTACH) {
        WPP_INIT_TRACING(MYDRIVER_TRACING_ID);

        g_hInstance = hInstance;
        DisableThreadLibraryCalls(hInstance);

    } else if (dwReason == DLL_PROCESS_DETACH) {
        WPP_CLEANUP();
    }

    return _AtlModule.DllMain(dwReason, lpReserved);
}

クライアントドライバーが DllMain 関数を実装している場合、Windows は DllMain をクライアントドライバーモジュールのエントリポイントと見なします。 Windows は、WUDFHost.exe にクライアントドライバーモジュールを読み込んだ後で、DllMain を呼び出します。 Windows は、Windows がメモリ内のクライアントドライバーをアンロードする直前に、DllMain を再度呼び出します。 DllMain は、ドライバーレベルでグローバル変数を割り当てて解放できます。テンプレートコードでは、クライアントドライバーは WPP トレースに必要なリソースを初期化して解放し、ATL クラスの DllMain 実装を呼び出します。

次のコードスニペットは、DllGetClassObject の実装を示しています

STDAPI
DllGetClassObject(
    __in REFCLSID rclsid,
    __in REFIID riid,
    __deref_out LPVOID FAR* ppv
    )
{
    return _AtlModule.DllGetClassObject(rclsid, riid, ppv);
}

テンプレートコードでは、クラスファクトリと DllGetClassObject が ATL に実装されます。上記のコードスニペットは、ATL DllGetClassObject 実装を呼び出すだけです。一般に、DllGetClassObject は次のタスクを実行する必要があります。

フレームワークによって渡される CLSID がクライアントドライバーの GUID であることを確認します。フレームワークは、ドライバーの INF ファイルからクライアントドライバーの CLSID を取得します。検証中に、指定した GUID が INF で指定した GUID と一致することを確認してください。
クライアントドライバーによって実装されるクラスファクトリをインスタンス化します。テンプレートコードでは、これは ATL クラスによってカプセル化されます。
クラスファクトリの IClassFactory インターフェイスへのポインターを取得し、取得したポインターをフレームワークに返します。

クライアントドライバーモジュールがメモリに読み込まれた後、フレームワークはドライバーが提供する DllGetClassObject 関数を呼び出します。 DllGetClassObject へのフレームワークの呼び出しでは、フレームワークは、クライアントドライバーを識別し、クラスファクトリの IClassFactory インターフェイスへのポインターを要求する CLSID を渡します。クライアントドライバーは、ドライバーコールバックの作成を容易にするクラスファクトリを実装します。したがって、クライアントドライバーには少なくとも 1 つのクラスファクトリが含まれている必要があります。その後、フレームワークは IClassFactory::CreateInstance を呼び出し、ドライバーコールバッククラスへの IDriverEntry ポインターを要求します。

Exports.def

フレームワークが DllGetClassObject を呼び出すには、クライアントドライバーが .def ファイルから関数をエクスポートする必要があります。ファイルは Visual Studio プロジェクトに既に含まれています。

; Exports.def : Declares the module parameters.

LIBRARY     "MyUSBDriver_UMDF_.DLL"

EXPORTS
        DllGetClassObject   PRIVATE

ドライバープロジェクトに含まれる Export.def の上記のコードスニペットでは、クライアントはドライバーモジュールの名前を LIBRARY として提供し、DllGetClassObject を EXPORTS の下に指定します。詳細については、「DEFファイルを使用した DLL からのエクスポート」を参照してください。

次の方法で共有

USB クライアントドライバーコード構造について (UMDF)

ドライバーコールバックのソースコード

デバイスコールバックのソースコード

IDriverEntry::OnDeviceAdd 実装

IPnpCallbackHardware の実装と USB 固有のタスク

キューのソースコード

IoQueue.h

ドライバーエントリのソースコード

Dllsup.cpp

Exports.def

フィードバック

その他のリソース

次の方法で共有

USB クライアント ドライバー コード構造について (UMDF)

ドライバー コールバックのソース コード

デバイス コールバックのソース コード

IDriverEntry::OnDeviceAdd 実装

IPnpCallbackHardware の実装と USB 固有のタスク

キューのソース コード

IoQueue.h

ドライバー エントリのソース コード

Dllsup.cpp

Exports.def

フィードバック

その他のリソース

USB クライアントドライバーコード構造について (UMDF)

ドライバーコールバックのソースコード

デバイスコールバックのソースコード

キューのソースコード

ドライバーエントリのソースコード