Gerenciando o sistema de arquivos

O Shell fornece várias maneiras de gerenciar sistemas de arquivos. O Shell fornece uma função, SHFileOperation, que permite que um aplicativo mova, copie, renomeie e exclua arquivos programaticamente. O Shell também suporta alguns recursos adicionais de gerenciamento de arquivos.

• Os documentos HTML podem ser conectados a arquivos relacionados, como arquivos gráficos ou folhas de estilo. Quando o documento é movido ou copiado, os arquivos conectados também são movidos ou copiados automaticamente.
• Para sistemas que estão disponíveis para mais de um usuário, os arquivos podem ser gerenciados por usuário. Os usuários têm acesso fácil aos seus arquivos de dados, mas não aos arquivos pertencentes a outros usuários.
• Se os arquivos de documentos forem adicionados ou modificados, eles poderão ser adicionados à lista de documentos recentes do Shell. Quando o usuário clica no comando Documents no menu Iniciar, uma lista de links para os documentos é exibida.

Este documento discute como essas tecnologias de gerenciamento de arquivos funcionam. Em seguida, ele descreve como usar o Shell para mover, copiar, renomear e excluir arquivos e como gerenciar objetos na Lixeira.

• Per-User Gerenciamento de Arquivos
• Os Meus Documentos e Minhas Imagens
• arquivos conectados
• Mover, copiar, renomear e excluir arquivos
  • Notificando o Shell
• exemplo simples de gerenciamento de arquivos com SHFileOperation
• Adicionando arquivos à lista de documentos recentes do Shell

Per-User Gestão de Ficheiros

O Shell do Windows 2000 permite que os arquivos sejam associados a um usuário específico para que os arquivos permaneçam ocultos de outros usuários. Em termos do sistema de arquivos, os arquivos são armazenados na pasta de perfil do usuário, normalmente C:\Documents and Settings\Nome de usuário\ em sistemas Windows 2000. Este recurso permite que muitas pessoas usem o mesmo computador, mantendo a privacidade de seus arquivos de outros usuários. Diferentes usuários podem ter diferentes programas disponíveis. Ele também fornece uma maneira simples para os administradores e aplicativos armazenarem coisas como ficheiros de inicialização (.ini) ou ficheiros .lnk. Os aplicativos podem, assim, preservar um estado diferente para cada usuário e recuperar facilmente esse estado específico quando necessário. Há também uma pasta de perfil para armazenar informações que são comuns a todos os usuários.

Como é inconveniente determinar qual usuário está conectado e onde seus arquivos estão localizados, as pastas padrão por usuário são pastas especiais e são identificadas por um CSIDL. Por exemplo, o CSIDL para a pasta Arquivos de Programas por usuário é CSIDL_PROGRAMS. Se seu aplicativo chamar SHGetFolderLocation ou SHGetFolderPath com um dos CSIDLs por usuário, a função retornará o ponteiro para uma lista de identificadores de item (PIDL) ou caminho apropriado para o usuário conectado no momento. Se seu aplicativo precisa recuperar o caminho ou PIDL da pasta de perfil, seu CSIDL é CSIDL_PROFILE.

Pastas Meus Documentos e Minhas Imagens

Um dos ícones padrão encontrados na área de trabalho é Meus Documentos. Quando você abre essa pasta, ela contém os arquivos de documento do usuário atual. A instância da área de trabalho de Meus Documentos é uma pasta virtual — um alias para o local do sistema de arquivos usado para armazenar fisicamente os documentos do usuário — localizada imediatamente abaixo da área de trabalho na hierarquia de namespace.

O objetivo das pastas Meus Documentos e Minhas Imagens é fornecer uma maneira simples e segura para os usuários acessarem seus arquivos de documentos e imagens em um sistema que pode ter vários usuários. Cada usuário recebe pastas separadas do sistema de arquivos para seus arquivos. Por exemplo, o local da pasta de documentos de um usuário no sistema de arquivos normalmente é algo como C:\Documents and Settings\nome de usuário\My Documents. Não há necessidade de os usuários saberem nada sobre a localização física de suas pastas do sistema de arquivos. Eles simplesmente acessam seus arquivos através do ícone Meus documentos.

Normalmente, não há necessidade de um aplicativo saber qual usuário está conectado ou onde no sistema de arquivos a pasta Meus Documentos do usuário está localizada. Em vez disso, o seu aplicativo pode recuperar o PIDL do ícone da área de trabalho Os Meus Documentos ao chamar o método IShellFolder::ParseDisplayName da área de trabalho. O nome de análise usado para identificar a pasta Meus Documentos não é um caminho de arquivo, mas sim ::{450d8fba-ad25-11d0-98a8-0800361b1103}. A expressão entre colchetes é a forma de texto do GUID Meus documentos. Por exemplo, para recuperar o PIDL de Meus Documentos, a sua aplicação deve usar esta chamada para IShellFolder::ParseDisplayName.

hr = psfDeskTop->ParseDisplayName(NULL, 
                                  NULL, 
                                  L"::{450d8fba-ad25-11d0-98a8-0800361b1103}", 
                                  &chEaten, 
                                  &pidlDocFiles, 
                                  NULL);

Uma vez que seu aplicativo tenha o Meus Documentos PIDL, ele pode lidar com a pasta da mesma forma que faria com uma pasta normal do sistema de arquivos — enumerando itens, analisando, vinculando e executando quaisquer outras operações de pasta válidas. O Shell mapeia automaticamente as alterações em Meus Documentos ou em suas subpastas para as pastas apropriadas do sistema de arquivos.

Se seu aplicativo precisar acessar a pasta real do sistema de arquivos que contém os documentos do usuário atual, passe CSIDL_PERSONAL para SHGetFolderLocation. A função retorna o PIDL da pasta do sistema de arquivos que é exibida na pasta Meus Documentos do usuário atual.

Arquivos conectados

Os documentos HTML geralmente têm vários arquivos gráficos associados, um arquivo de folha de estilo, vários arquivos Microsoft JScript (compatível com a especificação de linguagem ECMA 262) e assim por diante. Ao mover ou copiar o documento HTML principal, geralmente também deseja mover ou copiar os seus ficheiros associados para evitar a quebra de ligações. Infelizmente, não houve nenhuma maneira fácil até agora para determinar quais arquivos estão relacionados a qualquer documento HTML a não ser analisando seu conteúdo. Para aliviar esse problema, o Windows 2000 fornece uma maneira simples de ligar um documento HTML primário com o seu grupo de arquivos associados. Se a conexão de arquivo estiver ativada, quando o documento for movido ou copiado, todos os arquivos conectados irão com ele.

Para criar um grupo de arquivos conectados, o documento principal deve ter uma extensão de nome de arquivo .htm ou .html. Crie uma subpasta da pasta pai do documento principal. O nome da subpasta deve ser o nome do documento principal, menos a extensão .htm ou .html, seguido por uma das extensões listadas abaixo. As extensões mais usadas são ".files" ou "_files". Por exemplo, se o documento principal for chamado MyDoc.htm, nomear a subpasta "MyDoc_files" define a subpasta como o recipiente para os arquivos associados do documento. Se o documento principal for movido ou copiado, a subpasta e seus arquivos também serão movidos ou copiados.

Para alguns idiomas, é possível usar um equivalente localizado de "_files" para criar uma subpasta para arquivos conectados. A tabela a seguir lista as cadeias de caracteres válidas que podem ser acrescentadas a um nome de documento para criar uma subpasta de arquivos conectados. Observe que algumas dessas cadeias de caracteres têm '-' como seu primeiro caractere em vez de '_' ou '.'.

Se a conexão de arquivo está habilitada ou desabilitada é controlada por um valor REG_DWORD, NoFileFolderConnection, da seguinte chave do Registro.

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer

Esse valor normalmente não é definido e a conexão de arquivo está habilitada. Se necessário, você pode desativar a conexão de arquivo adicionando esse valor à chave e definindo-a como 1. Para habilitar a conexão de arquivo novamente, defina NoFileFolderConnection como zero.

Mover, copiar, renomear e excluir arquivos

O namespace não é estático e os aplicativos geralmente precisam gerenciar o sistema de arquivos executando uma das seguintes operações.

• Copiar um objeto para outra pasta.
• Mover um objeto para outra pasta.
• Eliminar um objeto
• Renomeando um objeto.

Estas operações são todas realizadas com SHFileOperation. Esta função usa um ou mais arquivos de origem e produz os arquivos de destino correspondentes. No caso da operação de exclusão, o sistema tenta colocar os arquivos excluídos na Lixeira.

Também é possível mover arquivos usando o funcionalidade de arrastar e soltar.

Para usar a função, deve-se preencher os membros de uma estrutura SHFILEOPSTRUCT e passá-la para SHFileOperation. Os principais membros da estrutura são pFrom e pTo.

O membro pFrom é uma cadeia de caracteres dupla nula-terminated que contém um ou mais nomes de arquivo de origem. Esses nomes podem ser caminhos totalmente qualificados ou curingas padrão do DOS, como *.*. Embora esse membro seja declarado como um null-terminated string, ele é usado como um buffer para armazenar vários nomes de arquivo. Cada nome de ficheiro deve ser terminado pelo usual caractere único NULL . Um caractere de NULL adicional deve ser anexado ao final do nome final para indicar o final de pFrom.

O membro pTo é uma cadeia de caracteres dupla nula-terminada, muito parecida com pFrom. O membro pTo contém um ou mais nomes de destino totalmente qualificados. Eles são embalados em pTo da mesma forma que são para pFrom. Se pTo contiver vários nomes, deve também definir o sinalizador FOF_MULTIDESTFILES no membro fFlags. O uso de pTo depende da operação descrita aqui.

• Para operações de cópia e movimentação, se todos os arquivos estiverem indo para um único diretório, pTo conterá o nome de diretório totalmente qualificado. Se os arquivos estiverem indo para destinos diferentes, pTo também pode conter um diretório ou nome de arquivo totalmente qualificado para cada arquivo de origem. Se um diretório não existir, o sistema o cria.
• Para operações de renomeação, pTo contém um caminho totalmente qualificado para cada arquivo de origem em pFrom.
• Para operações de exclusão, pTo não é utilizado.

Notificação ao Shell

Notifique o Shell da alteração depois de usar SHFileOperation para mover, copiar, renomear ou excluir arquivos, ou depois de executar qualquer outra ação que afete o namespace. Entre as ações que devem ser acompanhadas de notificação contam-se as seguintes:

• Adicionar ou eliminar ficheiros ou pastas.
• Mover, copiar ou renomear arquivos ou pastas.
• Alterar uma associação de ficheiro.
• Alterando atributos de arquivo.
• Adicionar ou remover unidades ou suportes de armazenamento.
• Criar ou desativar uma pasta partilhada.
• Alterar a lista de imagens do sistema.

Um aplicativo notifica o Shell chamando SHChangeNotify com os detalhes do que foi alterado. O Shell pode então atualizar sua imagem do namespace para refletir com precisão seu novo estado.

Exemplo simples de gerenciamento de arquivos com SHFileOperation

O aplicativo de console de exemplo a seguir ilustra o uso do SHFileOperation para copiar arquivos de um diretório para outro. Os diretórios de origem e destino, C:\My_Docs e C:\My_Docs2, são codificados no aplicativo para simplificar.

#include <shlobj.h>
#include <shlwapi.h>
#include <strsafe.h>

int main(void)
{
    IShellFolder *psfDeskTop = NULL;
    IShellFolder *psfDocFiles = NULL;
    LPITEMIDLIST pidlDocFiles = NULL;
    LPITEMIDLIST pidlItems = NULL;
    IEnumIDList *ppenum = NULL;
    SHFILEOPSTRUCT sfo;
    STRRET strDispName;
    TCHAR szParseName[MAX_PATH];
    TCHAR szSourceFiles[256];
    int i;
    int iBufPos = 0;
    ULONG chEaten;
    ULONG celtFetched;
    size_t ParseNameSize = 0;
    HRESULT hr;
    

    szSourceFiles[0] = '\0';
    hr = SHGetDesktopFolder(&psfDeskTop);

    hr = psfDeskTop->ParseDisplayName(NULL, NULL, L"c:\\My_Docs", 
         &chEaten, &pidlDocFiles, NULL);
    hr = psfDeskTop->BindToObject(pidlDocFiles, NULL, IID_IShellFolder, 
         (LPVOID *) &psfDocFiles);
    hr = psfDeskTop->Release();

    hr = psfDocFiles->EnumObjects(NULL,SHCONTF_FOLDERS | SHCONTF_NONFOLDERS, 
         &ppenum);

    while( (hr = ppenum->Next(1,&pidlItems, &celtFetched)) == S_OK 
       && (celtFetched) == 1)
    {
        psfDocFiles->GetDisplayNameOf(pidlItems, SHGDN_FORPARSING, 
            &strDispName);
        StrRetToBuf(&strDispName, pidlItems, szParseName, MAX_PATH);
        
        hr = StringCchLength(szParseName, MAX_PATH, &ParseNameSize);
        
        if (SUCCEEDED(hr))
        {
            for(i=0; i<=ParseNameSize; i++)
            {
                szSourceFiles[iBufPos++] = szParseName[i];
            }
            CoTaskMemFree(pidlItems);
        }
    }
    ppenum->Release();
    
    szSourceFiles[iBufPos] = '\0';

    sfo.hwnd = NULL;
    sfo.wFunc = FO_COPY;
    sfo.pFrom = szSourceFiles;
    sfo.pTo = "c:\\My_Docs2\0";
    sfo.fFlags = FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOCONFIRMMKDIR;

    hr = SHFileOperation(&sfo);
    
    SHChangeNotify(SHCNE_UPDATEDIR, SHCNF_PATH, (LPCVOID) "c:\\My_Docs2", 0);

    CoTaskMemFree(pidlDocFiles);
    psfDocFiles->Release();

    return 0;
}

A aplicação primeiro recupera um ponteiro para a interface IShellFolder da área de trabalho. Em seguida, ele recupera o PIDL do diretório de origem passando seu caminho totalmente qualificado para IShellFolder::ParseDisplayName. Observe que IShellFolder::P arseDisplayName requer que o caminho do diretório seja uma cadeia de caracteres Unicode. Em seguida, o aplicativo se liga ao diretório de origem e usa sua interface IShellFolder para recuperar a interfaceIEnumIDList de um objeto enumerador.

Como cada arquivo no diretório de origem é enumerado, IShellFolder::GetDisplayNameOf é usado para recuperar seu nome. O sinalizador SHGDN_FORPARSING é definido, o que faz com que IShellFolder::GetDisplayNameOf retorne o caminho totalmente qualificado do arquivo. Os caminhos de arquivo, incluindo os de terminação NULL caracteres, são concatenados em uma única matriz, szSourceFiles. Um segundo caractere NULL é anexado ao caminho final para encerrar a matriz corretamente.

Quando a enumeração estiver concluída, o aplicativo atribui valores a uma estrutura SHFILEOPSTRUCT. Observe que a matriz atribuída a pTo para especificar o destino também deve ser terminada por um NULLduplo. Nesse caso, ele é simplesmente incluído na cadeia de caracteres atribuída a pTo. Como este é um aplicativo de console, os sinalizadores FOF_SILENT, FOF_NOCONFIRMATION e FOF_NOCONFIRMMKDIR são definidos para suprimir quaisquer caixas de diálogo que possam aparecer. Depois que SHFileOperation retorna, SHChangeNotify é chamado para notificar o Shell da alteração. Em seguida, o aplicativo executa a limpeza habitual e retorna.

Adicionando arquivos à lista de documentos recentes do shell

O Shell mantém uma lista de documentos adicionados ou modificados recentemente para cada usuário. O usuário pode exibir uma lista de links para esses arquivos clicando em documentos no menu Iniciar. Tal como acontece com Meus documentos, cada usuário tem um diretório do sistema de arquivos para armazenar os links reais. Para recuperar o PIDL do diretório Recentes do utilizador atual, o seu aplicativo pode chamar SHGetFolderLocation com CSIDL_RECENT ou chamar SHGetFolderPath para recuperar o seu caminho.

Seu aplicativo pode enumerar o conteúdo da pasta Recente usando as técnicas discutidas anteriormente neste documento. No entanto, um aplicativo não deve modificar o conteúdo da pasta como se fosse uma pasta normal do sistema de arquivos. Se isso acontecer, a lista de documentos recentes do Shell não será atualizada corretamente e as alterações não serão refletidas no menu Iniciar. Em vez disso, para adicionar um link de documento à pasta Recente de um usuário, seu aplicativo pode chamar SHAddToRecentDocs. O Shell adicionará um link para a pasta apropriada do sistema de arquivos, bem como atualizará sua lista de documentos recentes e o menu Iniciar. Você também pode usar essa função para limpar a pasta.