Função SHLoadIndirectString (shlwapi.h)

Extrai um recurso de texto especificado quando dado esse recurso na forma de uma cadeia de caracteres indireta (uma cadeia de caracteres que começa com o símbolo '@').

Sintaxe

LWSTDAPI SHLoadIndirectString(
  [in]  PCWSTR pszSource,
  [out] PWSTR  pszOutBuf,
  [in]  UINT   cchOutBuf,
        void   **ppvReserved
);

Parâmetros

[in] pszSource

Tipo: PCWSTR

Um ponteiro para um buffer que contém a cadeia de caracteres indireta da qual o recurso será recuperado. Essa cadeia de caracteres deve começar com o símbolo '@' e usar um dos formulários discutidos na seção Comentários. Essa função aceitará com êxito uma cadeia de caracteres que não começa com um símbolo '@', mas a cadeia de caracteres será simplesmente passada inalterada para pszOutBuf.

[out] pszOutBuf

Tipo: PWSTR

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe o recurso de texto. Tanto pszOutBuf quanto pszSource podem apontar para o mesmo buffer, nesse caso, a cadeia de caracteres original será substituída.

[in] cchOutBuf

Tipo: UINT

O tamanho do buffer apontado por pszOutBuf, em caracteres.

ppvReserved

Tipo: void**

Não usado; definido como NULL.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Uma cadeia de caracteres indireta pode ser fornecida de várias formas, cada uma com sua própria interpretação:

• O nome do arquivo e a sintaxe de recurso ''' @filename, recurso '''

  A cadeia de caracteres é extraída do arquivo chamado, usando o valor do recurso como um localizador. Se o valor do recurso for zero ou maior, o número se tornará o índice da cadeia de caracteres no arquivo binário. Se o número for negativo, ele se tornará uma ID de recurso. A cadeia de caracteres recuperada é copiada para o buffer de saída e a função retorna S_OK.

• Nome do arquivo e ID do recurso com uma sintaxe ''' do modificador de versão @filename, recurso; v2 '''

  Esse formulário pode ser usado quando um recurso é alterado, mas ainda usa o mesmo índice ou ID que o recurso antigo. Sem um modificador de versão, o cache MUI (Interface do Usuário Multilíngue) não reconhecerá que o recurso foi alterado e não será atualizado. Acrescentando o modificador de versão, o valor é visto como um novo recurso e é adicionado ao cache. Observe que é recomendável que você use uma nova ID ou índice para um novo recurso e use um modificador de versão somente quando isso não for possível.

• Caminho do arquivo PRI e sintaxe de recurso ''' @{PRIFilepath?resource} '''

  O PRI (Índice de Recursos de Pacote) é um formato binário introduzido em Windows 8 que contém recursos indexados ou referências a recursos. O arquivo .pri é agrupado como parte do pacote de um aplicativo. Para obter mais informações sobre arquivos .pri, consulte Criando e recuperando recursos em aplicativos da Windows Store.

  A cadeia de caracteres é extraída do arquivo .pri chamado, usando o recurso como um localizador. A cadeia de caracteres recuperada é copiada para o buffer de saída e a função retorna S_OK. A cadeia de caracteres é extraída com base no ambiente atual do Shell ou em ResourceContext.

  Um exemplo desse tipo de cadeia de caracteres indireta é mostrado aqui.

  
  @{C:\Program Files\WindowsApps\Microsoft.Camera_6.2.8376.0_x64__8wekyb3d8bbwe\resources.pri? ms-resource://Microsoft.Camera/resources/manifestAppDescription}
  

• Nome do pacote e ID do recurso ''' sintaxe @{PackageFullName?resource} '''

  A cadeia de caracteres é extraída do arquivo Resources.pri armazenado no diretório raiz do aplicativo do pacote identificado por PackageFullName, usando o recurso como um localizador. A cadeia de caracteres recuperada é copiada para o buffer de saída e a função retorna S_OK. A cadeia de caracteres é extraída com base no ambiente do aplicativo ou em ResourceContext.

  Nota Essa cadeia de caracteres deve se referir a um pacote instalado para o usuário atual. Se isso não acontecer, a chamada falhará.
   
  Um exemplo desse tipo de cadeia de caracteres indireta é mostrado aqui. Neste exemplo, o nome de referência é totalmente qualificado, mas não contém nenhum namespace (por exemplo, "recursos"). A pilha de implantação expande o nome para procurá-lo em todos os namespaces.

  
  @{Microsoft.Camera_6.2.8376.0_x64__8wekyb3d8bbwe? ms-resource://Microsoft.Camera/manifestAppDescription}
  

  Neste próximo exemplo, o nome de referência totalmente qualificado especifica um namespace para limitar a pesquisa.

  
  @{Microsoft.Camera_6.2.8376.0_x64__8wekyb3d8bbwe? ms-resource://Microsoft.Camera/resources/manifestAppDescription}
  

Se a cadeia de caracteres não for uma cadeia de caracteres indireta, a cadeia de caracteres será copiada diretamente sem alteração para pszOutBuf e a função retornará S_OK.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlwapi.h
Biblioteca	Shlwapi.lib
DLL	Shlwapi.dll (versão 5.5 ou posterior)