Metodo IBackgroundCopyFile2::SetRemoteName (bits2_0.h)

Articolo
02/23/2024

Modifica il nome remoto in un nuovo URL in un processo di download.

Sintassi

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Parametri

[in] Val

Stringa con terminazione null contenente il nome del file nel server. Per informazioni sulla specifica del nome remoto, vedere la sezione RemoteName member and Notes della struttura BG_FILE_INFO .

Valore restituito

Questo metodo restituisce i valori restituiti seguenti, nonché altri.

Codice restituito	Descrizione
S_OK	Operazione riuscita
E_INVALIDARG	Il nuovo nome remoto è un URL non valido o il nuovo URL è troppo lungo (l'URL non può superare i 2.200 caratteri).
E_NOTIMPL	Non è possibile chiamare questo metodo per caricare o caricare processi di risposta; chiamare solo questo metodo per scaricare i processi.
BG_E_INVALID_STATE	Lo stato del processo non può essere BG_JOB_STATE_CANCELLED o BG_JOB_STATE_ACKNOWLEDGED.

Commenti

In genere, si chiama questo metodo se si vuole modificare il protocollo usato per trasferire il file (ad esempio, da SMB a HTTP) o se si vuole modificare il nome o il percorso del file.

Questo metodo non serializza quando restituisce. Per serializzare la modifica, sospendere il processo, chiamare questo metodo (se si modificano più file nel processo, usare un ciclo) e riprendere il processo. La chiamata al metodo IBackgroundCopyJob::Resume serializza la modifica.

Se il timestamp o la dimensione del file del nuovo nome remoto è diverso dal nome remoto precedente o il nuovo server non supporta la ripresa del checkpoint (per i nomi remoti HTTP), BITS riavvia il download. In caso contrario, il trasferimento riprende dalla stessa posizione del nuovo server. BITS non riavvia già i file trasferiti.

Se il nome remoto identifica un percorso SMB (Server Message Block), la tabella seguente identifica i possibili codici di errore che possono verificarsi dopo aver ripreso il processo. Questi errori inserisce il processo nello stato di BG_JOB_STATE_ERROR .

Codice di errore	Descrizione
`HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND)`	La directory non è stata trovata.
`HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)`	Impossibile trovare il file.
`HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)`	L'utente non ha accesso al file specificato in Val.

Esempio

Nell'esempio seguente viene illustrato come chiamare il metodo SetRemoteName per modificare il nome remoto di un file. L'esempio presuppone che la variabile IBackgroundCopyJob, pJob , sia valida e il processo contenga uno o più file.

     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.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista, Windows XP con SP2,KB842773 in Windows Server 2003 e Windows XP
Server minimo supportato	Windows Server 2008, Windows Server 2003 con SP1
Piattaforma di destinazione	Windows
Intestazione	bits2_0.h (includere Bits.h)
Libreria	Bits.lib
DLL	BitsPrx3.dll

Vedi anche

IBackgroundCopyFile2

IBackgroundCopyJob3::ReplaceRemotePrefix

Condividi tramite