Classe CStdioFile

Representa um arquivo de fluxo em tempo de execução C, conforme aberto pela função de tempo de execução fopen.

Sintaxe

class CStdioFile : public CFile

Membros

Construtores públicos

Nome	Descrição
CStdioFile::CStdioFile	Cria um objeto CStdioFile a partir de um ponteiro de caminho ou de arquivo.

Métodos públicos

Nome	Descrição
CStdioFile::Open	Sobrecarregado. Open foi projetado para ser usado com o construtor padrão CStdioFile (substitui CFile::Open).
CStdioFile::ReadString	Lê apenas uma linha de texto.
CStdioFile::Seek	Posiciona o ponteiro do arquivo atual.
CStdioFile::WriteString	Grava uma só linha de texto.

Membros de Dados Públicos

Nome	Descrição
CStdioFile::m_pStream	Contém um ponteiro para um arquivo aberto.

Comentários

Os arquivos de fluxo são armazenados em buffer e podem ser abertos no modo de texto (o padrão) ou no modo binário.

O modo de texto fornece processamento especial para pares de retorno de carro/feed de linha. Quando você escreve um caractere (0x0A) de feed de linha (nova linha) em um objeto CStdioFile de modo de texto, o par de bytes (0x0D, 0x0A) é enviado para o arquivo. Quando você lê, o par de bytes (0x0D, 0x0A) é convertido em apenas um byte 0x0A.

As funções Duplicate, LockRange e UnlockRange de CFile não são compatíveis com CStdioFile.

Se você chamar essas funções em um CStdioFile, você obterá um CNotSupportedException.

Para obter mais informações sobre como usar a CStdioFile, confira os artigos Arquivos em MFC e Tratamento de arquivos na Referência de biblioteca de runtime.

Hierarquia de herança

CObject

CFile

CStdioFile

Requisitos

Cabeçalho: afx.h

CStdioFile::CStdioFile

Constrói e inicializa um objeto CStdioFile.

CStdioFile();
CStdioFile(CAtlTransactionManager* pTM);
CStdioFile(FILE* pOpenStream);

CStdioFile(
    LPCTSTR lpszFileName,
    UINT nOpenFlags);

CStdioFile(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CAtlTransactionManager* pTM);

Parâmetros

pOpenStream
Especifica o ponteiro de arquivo retornado por uma chamada à função fopen de tempo de execução C.

lpszFileName
Especifica uma cadeia de caracteres que é o caminho para o arquivo desejado. O caminho pode ser relativo ou absoluto.

nOpenFlags
Especifica opções para criação de arquivo, compartilhamento de arquivos e modos de acesso a arquivos. Você pode especificar várias opções usando o operador OR (|) bit a bit.

Uma opção de modo de acesso de arquivo é exigida; outros modos são opcionais. Confira CFile::CFile para uma lista de opções de modo e outros sinalizadores. No MFC versão 3.0 e posterior, os sinalizadores de compartilhamento são permitidos.

pTM
Ponteiro para o objeto CAtlTransactionManager.

Comentários

O construtor padrão não anexa um arquivo ao objeto CStdioFile. Ao usar esse construtor, use o método CStdioFile::Open para abrir um arquivo e anexá-lo ao objeto CStdioFile.

O construtor de parâmetro único anexa um fluxo de arquivo aberto ao objeto CStdioFile. Os valores de ponteiro permitidos incluem os ponteiros de arquivo de entrada/saída predefinidos stdin. stdout ou stderr.

O construtor de dois parâmetros cria um objeto CStdioFile e abre o arquivo correspondente com o caminho fornecido.

Se você passar NULL para um pOpenStream ou lpszFileName, o construtor gerará uma CInvalidArgException*.

Se o arquivo não puder ser aberto ou criado, o construtor gerará um CFileException*.

Exemplo

TCHAR* pFileName = _T("CStdio_File.dat");
CStdioFile f1;
if(!f1.Open(pFileName, CFile::modeCreate | CFile::modeWrite 
   | CFile::typeText)) 
{
   TRACE(_T("Unable to open file\n"));
}

CStdioFile f2(stdout);
try
{
   CStdioFile f3( pFileName,
      CFile::modeCreate | CFile::modeWrite | CFile::typeText );
}
catch(CFileException* pe)
{
   TRACE(_T("File could not be opened, cause = %d\n"),
      pe->m_cause);
   pe->Delete();
}

CStdioFile::m_pStream

O membro de dados m_pStream é o ponteiro para um arquivo aberto, conforme retornado pela função fopen de tempo de execução C.

FILE* m_pStream;

Comentários

É NULL se o arquivo nunca foi aberto ou se foi fechado.

CStdioFile::Open

Sobrecarregado. Open foi projetado para ser usado com o construtor padrão CStdioFile.

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CAtlTransactionManager* pTM,
    CFileException* pError = NULL);

Parâmetros

lpszFileName
Uma cadeia de caracteres que é o caminho para o arquivo desejado. O caminho pode ser relativo ou absoluto.

nOpenFlags
Compartilhamento e modo de acesso. Ele especifica a ação a ser executada ao abrir o arquivo. Você pode combinar opções usando o operador OR (|) bit a bit. Uma permissão de acesso e uma opção de compartilhamento são necessárias; os modos modeCreate e modeNoInherit são opcionais.

pError
Um ponteiro para um objeto de exceção de arquivo existente que receberá o status de uma operação com falha.

pTM
Ponteiro para um objeto CAtlTransactionManager.

Valor de retorno

TRUE se for bem-sucedido, caso contrário, FALSE.

Comentários

CStdioFile::ReadString

Lê dados de texto em um buffer, até um limite de nMax-1 caracteres, do arquivo associado ao objeto CStdioFile.

virtual LPTSTR ReadString(
    LPTSTR lpsz,
    UINT nMax);

virtual BOOL ReadString(CString& rString);

Parâmetros

lpsz
Especifica um ponteiro para um buffer fornecido pelo usuário que receberá uma cadeia de caracteres de texto terminada em nulo.

nMax
Especifica o número máximo de caracteres a serem gravados no lpsz buffer, incluindo o nulo de terminação.

rString
Uma referência a um objeto CString que conterá a cadeia de caracteres quando a função retornar.

Valor de retorno

Um ponteiro para o buffer que contém os dados de texto. NULL se o fim do arquivo foi atingido sem ler dados; ou, se booliano, FALSE se o fim do arquivo foi atingido sem ler nenhum dado.

Comentários

A leitura é interrompida pelo primeiro caractere de nova linha. Se, nesse caso, menos de nMax-1 caracteres tiverem sido lidos, um caractere de nova linha será armazenado no buffer. Um caractere nulo ('\0') será acrescentado em ambos os casos.

CFile::Read também está disponível para entrada no modo de texto, mas não termina em um par de retorno de carro/feed de linha.

Observação

A versão CString dessa função remove o '\n' se presente; a versão LPTSTR não o faz.

Exemplo

CStdioFile f(stdin);
TCHAR buf[100];

f.ReadString(buf, 99);

CStdioFile::Seek

Reposiciona o ponteiro em um arquivo aberto anteriormente.

virtual ULONGLONG Seek(
    LONGLONG lOff,
    UINT nFrom);

Parâmetros

lOff
Número de bytes para mover o ponteiro.

nFrom
Modo de movimento do ponteiro. Deve ser um dos seguintes valores:

• CFile::begin: mova ponteiro de arquivo lOff bytes para a frente desde o início do arquivo.

• CFile::current: mova ponteiro de arquivo lOff bytes desde a posição atual no arquivo.

• CFile::end: mova ponteiro de arquivo lOff bytes desde o final do arquivo. Observe que lOff precisa ser negativo para buscar no arquivo existente; os valores positivos buscarão além do final do arquivo.

Valor de retorno

Se a posição solicitada for válida, Seek retornará o novo deslocamento de bytes desde o início do arquivo. Caso contrário, o valor retornado será indefinido e um objeto CFileException será gerado.

Comentários

A função Seek permite acesso aleatório ao conteúdo de um arquivo movendo o ponteiro em uma quantidade especificada, absolutamente ou relativamente. Nenhum dado é realmente lido durante a busca. Se a posição solicitada for maior que o tamanho do arquivo, o comprimento do arquivo será estendido para essa posição e nenhuma exceção será gerada.

Quando um arquivo é aberto, o ponteiro do arquivo é posicionado no deslocamento 0 desde o início do arquivo.

Essa implementação de Seek é baseada na função fseek da biblioteca de runtime (CRT). Há vários limites para o uso de Seek em fluxos abertos no modo de texto. Para obter mais informações, consulte fseeke _fseeki64.

Exemplo

O exemplo a seguir mostra como usar Seek para mover o ponteiro 1000 bytes desde o início do arquivo cfile. Observe que Seek não lê dados, portanto, você precisa chamar CStdioFile::ReadString posteriormente para ler dados.

CStdioFile cfile(_T("Stdio_Seek_File.dat"), CFile::modeWrite |
   CFile::modeCreate);
LONGLONG lOff = 1000;
ULONGLONG lActual = cfile.Seek(lOff, CFile::begin);

CStdioFile::WriteString

Grava dados de um buffer no arquivo associado ao objeto CStdioFile.

virtual void WriteString(LPCTSTR lpsz);

Parâmetros

lpsz
Especifica um ponteiro para um buffer que contém uma cadeia de caracteres terminada em nulo.

Comentários

O caractere nulo de terminação (\0) não é gravado no arquivo. Esse método grava caracteres de nova linha no arquivo lpsz como um par de retorno de carro/feed de linha.

Se você quiser gravar dados que não sejam encerrados em nulo em um arquivo, use CStdioFile::Write ou CFile::Write.

Esse método gerará uma CInvalidArgException* se você especificar NULL para o parâmetro lpsz.

Esse método gerará uma CFileException* em resposta a erros do sistema de arquivos.

Exemplo

CStdioFile f(stdout);
TCHAR buf[] = _T("test string");

f.WriteString(buf);

Confira também

Classe CFile
Gráfico da hierarquia
Classe CFile
CFile::Duplicate
CFile::LockRange
CFile::UnlockRange
Classe CNotSupportedException