BITS 転送ジョブのサーバー認証資格情報を指定する

[アーティクル]
03/12/2024

バックグラウンドインテリジェント転送サービス (BITS) 転送ジョブには、さまざまな認証スキームを指定できます。

次の手順では、認証スキームを取得し、認証 ID 構造を作成します。次に、アプリケーションによって BITS ダウンロードジョブが作成され、ジョブの資格情報が設定されます。ジョブが作成されると、アプリケーションはコールバックインターフェイスへのポインターを取得し、BITS 転送ジョブの状態をポーリングします。ジョブが完了すると、キューから削除されます。

この例では、「例: 共通クラス」で定義されているヘッダーと実装を使用します。

BITS 転送ジョブのサーバー認証資格情報を指定するには

BG_AUTH_SCHEME 値をスキーム名にマップするコンテナー構造を作成します。

struct
{
    LPCWSTR        Name;
    BG_AUTH_SCHEME Scheme;
}
SchemeNames[] =
{
    { L"basic",      BG_AUTH_SCHEME_BASIC },
    { L"digest",     BG_AUTH_SCHEME_DIGEST },
    { L"ntlm",       BG_AUTH_SCHEME_NTLM },
    { L"negotiate",  BG_AUTH_SCHEME_NEGOTIATE },
    { L"passport",   BG_AUTH_SCHEME_PASSPORT },

    { NULL,         BG_AUTH_SCHEME_BASIC }
};

CCoInitializer 関数を呼び出して COM パラメーターを初期化します。 CCoInitializer 関数の詳細については、「例: 共通クラス」を参照してください。
BG_AUTH_CREDENTIALS 構造体を準備します。この例では、SecureZeroMemory 関数を使用して、機密情報に関連付けられているメモリの場所をクリアします。 SecureZeroMemory 関数は WinBase.h で定義されています。

GetScheme 関数を使用して、サーバーへの接続に使用する認証スキームを取得します。

bool GetScheme( LPCWSTR s, BG_AUTH_SCHEME *scheme )
{
    int i;

    i = 0;
    while (SchemeNames[i].Name != NULL)
    {
        if (0 == _wcsicmp( s, SchemeNames[i].Name ))
        {

            *scheme = SchemeNames[i].Scheme;
            return true;
        }

        ++i;
    }

    return false;
}

BG_AUTH_CREDENTIALS 構造体に、GetScheme 関数によって返される認証スキームと、ServerAuthentication 関数に渡されたユーザー名とパスワードを設定します。
IBackgroundCopyJob インターフェイス (pJob) へのポインターを取得します。
CoInitializeSecurity を呼び出して COM プロセスのセキュリティを初期化します。 BITS には、少なくとも IMPERSONATE レベルの偽装が必要です。 BITS は、適切な偽装レベルが設定されていない場合、E_ACCESSDENIED で失敗します。
IBackgroundCopyManager インターフェイスへのポインターを取得し、CoCreateInstance 関数を呼び出して BITS への初期ロケーターを取得します。
IBackgroundCopyManager::CreateJob メソッドを呼び出して、転送ジョブを作成します。
CNotifyInterface コールバックインターフェイスへのポインターを取得し、IBackgroundCopyJob::SetNotifyInterface メソッドを呼び出して、ジョブ関連のイベントの通知を受信します。 CNotifyInterface の詳細については、「例: 共通クラス」を参照してください。
IBackgroundCopyJob::SetNotifyFlags メソッドを呼び出して、受信する通知の種類を設定します。この例では、BG_NOTIFY_JOB_TRANSFERRED フラグと BG_NOTIFY_JOB_ERROR フラグが設定されています。
IBackgroundCopyJob2 インターフェイスへのポインターを取得します。 IBackgroundCopyJob2 ポインターを使用して、ジョブに追加のプロパティを設定します。このプログラムでは、IBackgroundCopyJob2::SetCredentials メソッドを使用して BITS 転送ジョブの資格情報を設定します。
IBackgroundCopyJob::AddFile を呼び出して、BITS 転送ジョブにファイルを追加します。この例では、IBackgroundCopyJob::AddFile メソッドは、ServerAuthentication 関数に渡された remoteFile 変数と localFile 変数を使用します。
ファイルが追加されたら、IBackgroundCopyJob::Resume を呼び出してジョブを再開します。
ジョブの転送中にコールバックインターフェイスからの Quit メッセージを待機する while ループを設定します。

Note

この手順は、COM アパートメントがシングルスレッドアパートメントである場合にのみ必要です。詳細については、「シングルスレッドアパートメント」を参照してください。
```
// Wait for QuitMessage from CallBack
    DWORD dwLimit = GetTickCount() + (15 * 60 * 1000);  // set 15 minute limit
    while (dwLimit > GetTickCount())
    {
        MSG msg;

        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) 
        { 
            // If it is a quit message, exit.
            if (msg.message == WM_QUIT) 
            {
                return;
            }

            // Otherwise, dispatch the message.
            DispatchMessage(&msg); 
        } // End of PeekMessage while loop
    }
```
前のループでは、GetTickCount 関数を使用して、ジョブの転送が開始されてから経過したミリ秒数を取得します。
BITS 転送ジョブが完了したら、IBackgroundCopyJob::Complete を呼び出して、キューからジョブを削除します。

次のコード例では、BITS 転送ジョブのサーバー認証資格情報を指定します。

#include <bits.h>
#include <bits4_0.h>
#include <stdio.h>
#include <tchar.h>
#include <lm.h>
#include <iostream>
#include <exception>
#include <string>
#include <atlbase.h>
#include <memory>
#include <new>
#include "CommonCode.h"

//
// Retrieve BG_AUTH_SCHEME from scheme name.
//
//
struct
{
    LPCWSTR        Name;
    BG_AUTH_SCHEME Scheme;
}
SchemeNames[] =
{
    { L"basic",      BG_AUTH_SCHEME_BASIC },
    { L"digest",     BG_AUTH_SCHEME_DIGEST },
    { L"ntlm",       BG_AUTH_SCHEME_NTLM },
    { L"negotiate",  BG_AUTH_SCHEME_NEGOTIATE },
    { L"passport",   BG_AUTH_SCHEME_PASSPORT },

    { NULL,         BG_AUTH_SCHEME_BASIC }
};

bool GetScheme( LPCWSTR s, BG_AUTH_SCHEME *scheme )
{
    int i;

    i = 0;
    while (SchemeNames[i].Name != NULL)
    {
        if (0 == _wcsicmp( s, SchemeNames[i].Name ))
        {

            *scheme = SchemeNames[i].Scheme;
            return true;
        }

        ++i;
    }

    return false;
}

void ServerAuthentication(const LPWSTR &remoteFile, const LPWSTR &localFile, const LPWSTR &scheme, const LPWSTR &username, const LPWSTR &password)
{

 // If CoInitializeEx fails, the exception is unhandled and the program terminates  
 CCoInitializer coInitializer(COINIT_APARTMENTTHREADED);
    
    // Prepare the credentials structure.
    BG_AUTH_CREDENTIALS cred;
    ZeroMemory(&cred, sizeof(cred));
    if (!GetScheme(scheme,&cred.Scheme))
    {
        wprintf(L"Invalid authentication scheme specified\n");
        return;
    }

    cred.Target = BG_AUTH_TARGET_SERVER;
    cred.Credentials.Basic.UserName = username;
    if (0 == _wcsicmp(cred.Credentials.Basic.UserName, L"NULL"))
    {
        cred.Credentials.Basic.UserName = NULL;
    }

    cred.Credentials.Basic.Password = password;
    if (0 == _wcsicmp(cred.Credentials.Basic.Password, L"NULL"))
    {
        cred.Credentials.Basic.Password = NULL;
    }

    CComPtr<IBackgroundCopyJob> pJob;
    try
    {
        //The impersonation level must be at least RPC_C_IMP_LEVEL_IMPERSONATE.
        HRESULT hr = CoInitializeSecurity(NULL, 
            -1, 
            NULL, 
            NULL,
            RPC_C_AUTHN_LEVEL_CONNECT,
            RPC_C_IMP_LEVEL_IMPERSONATE,
            NULL, 
            EOAC_DYNAMIC_CLOAKING, 
            0);
        if (FAILED(hr))
        {
            throw MyException(hr, L"CoInitializeSecurity");
        }

        // Connect to BITS.
        CComPtr<IBackgroundCopyManager> pQueueMgr;
        hr = CoCreateInstance(__uuidof(BackgroundCopyManager), NULL,
            CLSCTX_LOCAL_SERVER,
            __uuidof(IBackgroundCopyManager),
            (void**)&pQueueMgr);

        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"CoCreateInstance");
        }

        // Create a job.
        wprintf(L"Creating Job...\n");

        GUID guidJob;
        hr = pQueueMgr->CreateJob(L"BitsAuthSample",
            BG_JOB_TYPE_DOWNLOAD,
            &guidJob,
            &pJob);

        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"CreateJob");
        }

        // Set the File Completed call.
        CComPtr<CNotifyInterface> pNotify;
        pNotify = new CNotifyInterface();
        hr = pJob->SetNotifyInterface(pNotify);
        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"SetNotifyInterface");
        }
        hr = pJob->SetNotifyFlags(BG_NOTIFY_JOB_TRANSFERRED | 
            BG_NOTIFY_JOB_ERROR);

        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"SetNotifyFlags");
        }

        // Set credentials.
        CComPtr<IBackgroundCopyJob2> job2;
        hr = pJob.QueryInterface(&job2);
        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"QueryInterface");
        }

        hr = job2->SetCredentials(&cred);
        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"SetCredentials");
        }

        // Add a file.
        wprintf(L"Adding File to Job\n");
        hr = pJob->AddFile(remoteFile, localFile);
        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"AddFile");
        }

        //Resume the job.
        wprintf(L"Resuming Job...\n");
        hr = pJob->Resume();
        if (FAILED(hr))
        {
            // Failed to connect.
            throw MyException(hr, L"Resume");
        }
    }
    catch(const std::bad_alloc &)
    {
        wprintf(L"Memory allocation failed");
        if (pJob)
        {
            pJob->Cancel();
        }

        return;
    }
    catch(const MyException &ex)
    {
        wprintf(L"Error %x occurred during operation", ex.Error);
        if (pJob)
        {
            pJob->Cancel();
        }

        return;
    }

    wprintf(L"Transferring file and waiting for callback.\n");

    // Wait for QuitMessage from CallBack.
    DWORD dwLimit = GetTickCount() + (15 * 60 * 1000);  // set 15 minute limit
    while (dwLimit > GetTickCount())
    {
        MSG msg;

        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) 
        { 
            // If it is a quit message, exit.
            if (msg.message == WM_QUIT) 
            {
                return;
            }

            // Otherwise, dispatch the message.
            DispatchMessage(&msg); 
        } // End of PeekMessage while loop
    }

    pJob->Cancel();
    return;
}

void _cdecl _tmain(int argc, LPWSTR* argv)
{   
    if (argc != 6)
    {
        wprintf(L"Usage:");
        wprintf(L"%s", argv[0]);
        wprintf(L" [remote name] [local name] [server authentication scheme =\"NTLM\"|\"NEGOTIATE\"|\"BASIC\"|\"DIGEST\"] [username] [password]\n");
        return;
    }

    ServerAuthentication(argv[1], argv[2], argv[3], argv[4], argv[5]); 

}

IBackgroundCopyManager
IBackgroundCopyJob
IBackgroundCopyJob2
例: 共通クラス

次の方法で共有

BITS 転送ジョブのサーバー認証資格情報を指定する

フィードバック

その他のリソース

次の方法で共有

BITS 転送ジョブのサーバー認証資格情報を指定する

関連トピック

フィードバック

その他のリソース