IBackgroundCopyFile2::SetRemoteName-Methode (bits2_0.h)

Ändert den Remotenamen in eine neue URL in einem Downloadauftrag.

Syntax

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Die 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"- und "Hinweise" der BG_FILE_INFO-Struktur .

Rückgabewert

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

Bemerkungen

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 in HTTP), oder wenn Sie den Dateinamen oder Pfad ändern möchten.

Diese Methode serialisiert nicht, wenn sie zurückgegeben wird. Um die Änderung zu serialisieren, halten Sie den Auftrag an, rufen Sie diese Methode auf (wenn sie mehrere Dateien im Auftrag ändern, eine Schleife verwenden), 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 den Prüfpunkt-Lebenslauf (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, identifiziert die folgende Tabelle mögliche Fehlercodes, die nach dem Fortsetzen des Auftrags auftreten können. Diese Fehler platzieren den Auftrag im BG_JOB_STATE_ERROR Zustand.

Examples

Das folgende Beispiel zeigt, wie die SetRemoteName-Methode aufgerufen wird, um den Remotenamen einer Datei zu ändern. Im Beispiel wird davon ausgegangen, dass die Variable "IBackgroundCopyJob ", 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

Siehe auch

IBackgroundCopyFile2

IBackgroundCopyJob3::ReplaceRemotePrefix