IBackgroundCopyFile2::SetRemoteName-Methode (bits2_0.h)

Artikel
02/23/2024

Ändert den Remotenamen in einer neuen URL in einem Downloadauftrag.

Syntax

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Parameter

[in] Val

Null-beendete Zeichenfolge, die den Namen der Datei auf dem Server enthält. Informationen zum Angeben des Remotenamens finden Sie im Abschnitt RemoteName-Member und Hinweise der BG_FILE_INFO-Struktur .

Rückgabewert

Diese Methode gibt die folgenden Rückgabewerte sowie andere rückgabewerte zurück.

Rückgabecode	Beschreibung
S_OK	Erfolg
E_INVALIDARG	Der neue Remotename ist eine ungültige URL, oder die neue URL ist zu lang (die URL darf 2.200 Zeichen nicht überschreiten).
E_NOTIMPL	Sie können diese Methode nicht für Upload- oder Upload-Antwortaufträge aufrufen. Rufen Sie diese Methode nur für Downloadaufträge auf.
BG_E_INVALID_STATE	Der Status des Auftrags kann nicht BG_JOB_STATE_CANCELLED oder BG_JOB_STATE_ACKNOWLEDGED sein.

Hinweise

In der Regel rufen Sie diese Methode auf, wenn Sie das Protokoll ändern möchten, das zum Übertragen der Datei verwendet wird (z. B. von SMB zu HTTP) oder wenn Sie den Dateinamen oder Pfad ändern möchten.

Diese Methode serialisiert sich nicht, wenn sie zurückgibt. Um die Änderung zu serialisieren, setzen Sie den Auftrag an , rufen Sie diese Methode auf (wenn Sie mehrere Dateien im Auftrag ändern, verwenden Sie eine Schleife), und setzen Sie den Auftrag fort. Durch Aufrufen der IBackgroundCopyJob::Resume-Methode wird die Änderung serialisiert.

Wenn sich der Zeitstempel oder die Dateigröße des neuen Remotenamens vom vorherigen Remotenamen unterscheidet oder der neue Server die Prüfpunkt-Fortsetzung (für HTTP-Remotenamen) nicht unterstützt, startet BITS den Download neu. Andernfalls wird die Übertragung von derselben Position auf dem neuen Server fortgesetzt. BITS startet bereits übertragene Dateien nicht neu.

Wenn der Remotename einen SMB-Pfad (Server Message Block) identifiziert, sind in der folgenden Tabelle mögliche Fehlercodes aufgeführt, die auftreten können, nachdem Sie den Auftrag fortgesetzt haben. Diese Fehler versetzen den Auftrag in den BG_JOB_STATE_ERROR Zustand.

Fehlercode	BESCHREIBUNG
`HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND)`	Das Verzeichnis wurde nicht gefunden.
`HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)`	Die Datei wurde nicht gefunden.
`HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)`	Der Benutzer hat keinen Zugriff auf die in Val angegebene Datei.

Beispiele

Das folgende Beispiel zeigt, wie Sie die SetRemoteName-Methode aufrufen, um den Remotenamen einer Datei zu ändern. Im Beispiel wird davon ausgegangen, dass die IBackgroundCopyJob-Variable pJob gültig ist und der Auftrag mindestens eine Datei enthält.

     IBackgroundCopyJob *pJob;
     IEnumBackgroundCopyFiles* pFiles = NULL;
     IBackgroundCopyFile* pFile = NULL;
     IBackgroundCopyFile2* pFile2 = NULL;
     WCHAR* pRemoteFileName = NULL;
     ULONG cFileCount = 0;

     hr = pJob->Suspend();
     hr = pJob->EnumFiles(&pFiles);
     if (SUCCEEDED(hr))
     {
          //Get the count of files in the job. 
          hr = pFiles->GetCount(&cFileCount);

          //Enumerate the files in the job.
          for (ULONG idx=0; idx<cFileCount; idx++)
          {
               hr = pFiles->Next(1, &pFile, NULL);
               if (S_OK == hr)
               {
                    //Get the local name of the file.
                    hr = pFile->GetRemoteName(&pRemoteFileName);
                    if (SUCCEEDED(hr))
                    {
                         //Determine if you want to replace the remote name of this file.
                         if (<CONDITIONGOESHERE>)
                         {
                              //Need to query the IBackgroundCopyFile interface for an IBackgroundCopyFile2
                              //interface pointer. The IBackgroundCopyFile2 interface contains the SetRemoteName method.
                              hr = pFile->QueryInterface(__uuidof(IBackgroundCopyFile2), (void**)&pFile2);
                              if (S_OK == hr)
                              {
                                   hr = pFile2->SetRemoteName(L"<NEWURLGOESHERE>");
                                   if (FAILED(hr))
                                   {
                                        //Handle error. 
                                        //Returns E_NOTIMPL if not a download job.
                                        //Returns E_INVALIDARG if invalid URL.
                                   }
                              }
                              else
                              {
                                   //handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
                                   //running on the computer is less than BITS 2.0.
                              }
                         }
                         CoTaskMemFree(pRemoteFileName); 
                    }    
                    pFile->Release(); 
                    pFile = NULL;
               }
               else
               {
                    //Handle error
                    break;
               }
          }

          pFiles->Release();
          pFiles = NULL;
     }

     hr = pJob->Resume(); //Force the job to serialize.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP2, KB842773 unter Windows Server 2003 und Windows XP
Unterstützte Mindestversion (Server)	Windows Server 2008, Windows Server 2003 mit SP1
Zielplattform	Windows
Kopfzeile	bits2_0.h (Bits.h einschließen)
Bibliothek	Bits.lib
DLL	BitsPrx3.dll

Weitere Informationen

IBackgroundCopyFile2

IBackgroundCopyJob3::ReplaceRemotePrefix

Share via