Método IBackgroundCopyFile2::SetRemoteName (bits2_0.h)

Altera o nome remoto para uma nova URL em um trabalho de download.

Sintaxe

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Parâmetros

[in] Val

Cadeia de caracteres terminada em nulo que contém o nome do arquivo no servidor. Para obter informações sobre como especificar o nome remoto, consulte a seção Membro remoteName e Comentários da estrutura BG_FILE_INFO .

Retornar valor

Esse método retorna os seguintes valores retornados, bem como outros.

Código de retorno	Descrição
S_OK	Êxito
E_INVALIDARG	O novo nome remoto é uma URL inválida ou a nova URL é muito longa (a URL não pode exceder 2.200 caracteres).
E_NOTIMPL	Você não pode chamar esse método para trabalhos de upload ou upload-reply; chame esse método apenas para trabalhos de download.
BG_E_INVALID_STATE	O estado do trabalho não pode ser BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.

Comentários

Normalmente, você chama esse método se quiser alterar o protocolo usado para transferir o arquivo (por exemplo, de SMB para HTTP) ou se quiser alterar o nome ou caminho do arquivo.

Esse método não serializa quando retorna. Para serializar a alteração, suspenda o trabalho, chame esse método (se alterar vários arquivos no trabalho, use um loop) e retome o trabalho. Chamar o método IBackgroundCopyJob::Resume serializa a alteração.

Se o carimbo de data/hora ou o tamanho do arquivo do novo nome remoto for diferente do nome remoto anterior ou o novo servidor não oferecer suporte à retomada de ponto de verificação (para nomes remotos HTTP), o BITS reiniciará o download. Caso contrário, a transferência será retomada da mesma posição no novo servidor. O BITS não reinicia arquivos já transferidos.

Se o nome remoto identificar um caminho SMB (bloco de mensagens do servidor), a tabela a seguir identificará possíveis códigos de erro que podem ocorrer depois que você retomar o trabalho. Esses erros colocam o trabalho no estado BG_JOB_STATE_ERROR .

Código do erro	Descrição
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND)	O diretório não foi encontrado.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	O arquivo não foi encontrado.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	O usuário não tem acesso ao arquivo especificado no Val.

 

Exemplos

O exemplo a seguir mostra como chamar o método SetRemoteName para alterar o nome remoto de um arquivo. O exemplo pressupõe que a variável IBackgroundCopyJob , pJob, seja válida e o trabalho contenha um ou mais arquivos.

     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.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista, Windows XP com SP2,KB842773 no Windows Server 2003 e Windows XP
Servidor mínimo com suporte	Windows Server 2008, Windows Server 2003 com SP1
Plataforma de Destino	Windows
Cabeçalho	bits2_0.h (inclua Bits.h)
Biblioteca	Bits.lib
DLL	BitsPrx3.dll

Confira também

IBackgroundCopyFile2

IBackgroundCopyJob3::ReplaceRemotePrefix