winbase.h


CreateFile

Crea, abre o trunca un fichero, pipe, recurso de comunicación, dispositivo de disco o consola. Devuelve un manipulador que puede ser usado para acceder al objeto. También puede abrir y retornar un manipulador a un directorio.

Sintaxis

HANDLE CreateFile(
    LPCTSTR lpFileName,                           // dirección del nombre de fichero
    DWORD dwDesiredAccess,                        // modo de acceso (lectura-escritura)
    DWORD dwShareMode,                            // modo de share (compartir) 
    LPSECURITY_ATTRIBUTES  lpSecurityAttributes,  // dirección del descriptor de seguridad
    DWORD dwCreationDistribution,                 // modo de creación
    DWORD dwFlagsAndAttributes,                   // atributos de fichero
    HANDLE hTemplateFile                          // manipulador de fichero con atributos a copiar
   );

Parámetros

lpFileName: apunta a una cadena terminada en cero que especifica el nombre del fichero, pipe, recurso de comunicaciones, dispositivo de disco o consola a crear, abrir o truncar.

Si *lpFileName es un camino, existe un límite de tamaño de cadena por defecto de MAX_PATH caracteres. Este límite está relacionado con el modo en que la función CreateFile trata los caminos.

Windows NT: se puede superar este límite y enviar caminos más largos que MAX_PATH caracteres llamando a la versión larga (W) de CreateFile y precediendo el camino con "\\?\". El prefijo "\\?\" le indica a la función que ignore el límite del camino. Esto permite usar caminos con tamaños cercanos a los 32k caracteres Unicode. Se deben usar caminos "fully-qualified" con esta técnica. Esto también funciona con nombres UNC. El prefijo "\\?\" se ignora como parte del camino. Por ejemplo, "\\?\C:\myworld\private" se toma como "C:\myworld\private", y "\\?\UNC\tom_1\hotstuff\coolapps" como "\\tom_1\hotstuff\coolapps".

dwDesiredAccess: especifica el tipo de acceso al fichero u otro objeto. Una aplicación puede obtener acceso de lectura, escritura, ambos o acceso de consulta de dispositivo. Se pueden usar las siguientes constantes de flag para definir valores para este parámetro, se deben especificar GENERIC_READ y GENERIC_WRITE para obtener un acceso de lectura-escritura:

Valor Significado
0 Permite a una aplicación consultar los atributos de un dispositivo sin acceder a él.
GENERIC_READ Especifica acceso de lectura al fichero. Los datos pueden ser leídos desde el fichero y el puntero del fichero puede ser movido.
GENERIC_WRITE Especifica acceso de escritura al fichero. Los datos pueden ser escritos al fichero y el puntero del fichero movido.

dwShareMode: especifica cómo puede ser compartido el fichero. Este parámetro debe ser alguna combinación de los siguientes valores:

Valor Significado
0 Evita que el fichero pueda ser compartido.
FILE_SHARE_READ Puede abrirse el fichero para acceso en lectura el fichero para realizar otras operaciones. Si la función CreateFile esta abriendo el cliente final de un mailslot, se especifica este flag.
FILE_SHARE_WRITE Pueden realizarse otras operaciones en el fichero con acceso para escritura.

lpSecurityAttributes: apunta a una estructura SECURITY_ATTRIBUTES que especifica los atributos de seguridad del fichero. El sistema de ficheros debe soportar este parámetro para que tenga algún efecto.

dwCreationDistribution: especifica la acción a realizar con ficheros que ya existan, y que acciones realizar con los que no existan. Para mayor información sobre este parámetro, ver la sección de observaciones. Este parámetro debe tomar uno de los siguientes valores:

Valor Significado
CREATE_NEW Crea un fichero nuevo. La función falla si el fichero especificado ya existe.
CREATE_ALWAYS Crea un fichero nuevo. La función sobrescribe el fichero si existe.
OPEN_EXISTING Abre el fichero. La función falla si el fichero no existe.
Ver la sección de observaciones para ver por qué es necesario usar OPEN_EXISTING si se usa CreateFile para un dispositivo, incluyendo la consola.
OPEN_ALWAYS Abre el fichero, si existe. Si el fichero no existe, la función crea el fichero como si se hubiera especificado el valor CREATE_NEW.
TRUNCATE_EXISTING Abre el fichero. Una vez abierto, el fichero es truncado tal como si su tamaño fuera de cero bytes. EL proceso que llama a la función debe abrir el fichero al menos con acceso GENERIC_WRITE. La función falla si el fichero no existe.

dwFlagsAndAttributes: especifica los atributos y flags del fichero.
Se acepta cualquier combinación de los siguientes atributos, excepto cualquiera contraria a FILE_ATTRIBUTE_NORMAL.

Atributo Significado
FILE_ATTRIBUTE_ARCHIVE Este fichero es un fichero de archivo. Las aplicaciones usan este atributo para marcar ficheros para backup o para borrar.
FILE_ATTRIBUTE_COMPRESSED El fichero o el directorio está comprimido. Para un fichero, esto significa que todos los datos del fichero están comprimidos. Para un directorio, esto significa que por defecto se comprimirán todos los ficheros y directorios creados en él.
FILE_ATTRIBUTE_NORMAL El fichero no tiene atributos seleccionados. Este atributo es válido sólo si se usa solo.
FILE_ATTRIBUTE_HIDDEN El fichero es oculto. No se incluye en un listado normal del directorio.
FILE_ATTRIBUTE_READONLY El fichero es sólo de lectura. Las aplicaciones pueden leer el fichero pero no pueden escribir en él o borrarlo.
FILE_ATTRIBUTE_SYSTEM El fichero es parte o se usa exclusivamente por el sistema operativo.

Cualquier combinación de los flags siguientes es aceptable.

Flag Significadoh
FILE_FLAG_WRITE_THROUGH Indica al sistema operativo para que escriba sin usar ningún caché intermedio directamente al fichero. El sistema operativo puede seguir usando operaciones de escritura en caché, pero nada le entretiene a la hora de vaciarlo.
FILE_FLAG_OVERLAPPED

Indica al sistema operativo para que inicialice el fichero, de modo que si operaciones como ReadFile, WriteFile, ConnectNamedPipe y TransactNamedPipe toman una cantidad significativa de tiempo de proceso retornen con ERROR_IO_PENDING. Cuando la operación termina, se activa un evento para señalizar el estado.

Cuando se especifica FILE_FLAG_OVERLAPPED, las funciones ReadFile y WriteFile deben especificar una estructura OVERLAPPED. Es decir, cuando de especifique FILE_FLAG_OVERLAPPED, la aplicación debe realizar lecturas y escrituras superpuestas (overlapped).

Cuando se especifique FILE_FLAG_OVERLAPPED, el sistema operativo no mantiene el puntero del fichero. La posición del fichero debe ser pasada como parte del parámetro lpOverlapped (apuntado por una estructura OVERLAPPED) para las funciones ReadFile yWriteFile.

Este flag también permite que más de una operación se realice simultáneamente con el mismo manipulador (una lectura y escritura simultaneas, por ejemplo).

FILE_FLAG_NO_BUFFERING

Indica al sistema operativo para que abra el fichero sin caché ni buffers intermedios. Esto puede proporcionar mejoras de comportamiento en algunas situaciones.

Una aplicación debe cumplir ciertos requisitos cuando trabaje con ficheros abiertos con FILE_FLAG_NO_BUFFERING:

  • El acceso al fichero debe comenzar con un desplazamiento dentro del fichero que debe ser múltiplo del tamaño del sector del volumen.
  • Los accesos al fichero deben ser para un número de bytes que sea múltiplo entero del tamaño del sector del volumen. Por ejemplo, si el tamaño del sector es de 512 bytes, la aplicación puede hacer lecturas y escrituras de 512, 1024 o 2048 bytes, pero no de 335, 981 o 7171 bytes.
  • Las direcciones de Buffer para operaciones de lectura y escritura deben estar alineadas en direcciones de memoria que sean múltiplos enteros del tamaño del sector del volumen.

La aplicación puede determinar el tamaño del sector del volumen mediante una llamada a la función GetDiskFreeSpace.

FILE_FLAG_RANDOM_ACCESS

Indica que el fichero será accedido aleatoriamente. Windows usa este flag para optimizar el caché del fichero.

FILE_FLAG_SEQUENTIAL_SCAN

Indica que el fichero será accedido secuencialmente desde el principio al final. Windows usa este flag para optimizar el caché del fichero. Si una aplicación mueve el puntero del fichero para acceso aleatorio, no se optimiza el caché, pero se garantiza que la operación se realiza correctamente.

Especificar este flag puede mejorar el comportamiento para aplicaciones que lean ficheros largos usando acceso secuencial. Las mejoras de comportamiento pueden ser también notables para aplicaciones que lean ficheros largos secuencialmente, pero que ocasionalmente se salten pequeños rangos de bytes.

FILE_FLAG_DELETE_ON_CLOSE

Indica al sistema operativo que debe borrar el fichero inmediatamente después de que todos sus manipuladores hayan sido cerrados.

Si usas este flag cuando llames a CreateFile, entonces abre el fichero de nuevo, y a continuación cierra el manipulador para el que se especificó FILE_FLAG_DELETE_ON_CLOSE, el fichero no debería borrarse hasta que se haya cerrado el segundo manipulador y cualquier otro manipulador del fichero.

FILE_FLAG_BACKUP_SEMANTICS

Sólo Windows NT: indica que el fichero será abierto o creado para una operación de backup o restore. El sistema operativo asegura que el proceso ignora las comprobaciones de seguridad, suministrando el permiso necesario para hacerlo. Los permisos relevantes son SE_BACKUP_NAME y SE_RESTORE_NAME.

Una aplicación de Windows NT puede activar este flag para obtener un manipulador de un directorio. Un manipulador de directorio puede ser pasado a algunas funciones Win32 en lugar de un manipulador a un fichero.

FILE_FLAG_POSIX_SEMANTICS Indica que el fichero será accedido de acuerdo con reglas POSIX. Esto incluye permitir que ficheros que sólo difieran en el tipo de letra (mayúsculas o minúsculas), para sistemas de ficheros que soporten estos nombres. Hay que tener cuidado cuando se use esta opción porque los ficheros creados con este flag pueden no ser accesibles por aplicaciones escritas para MS-DOS, Windows 3.x o Windows NT.

Si la función CreateFile abre la parte del cliente de un named pipe, el parámetro dwFlagsAndAttributes puede también contener información sobre Calidad de Seguridad del Servicio. Cuando la aplicación especifica el flag SECURITY_SQOS_PRESENT, el parámetro dwFlagsAndAttributes puede contener uno o más de los siguientes valores:

Valor Significado
SECURITY_ANONYMOUS Indica el nivel de "Anonymous" para un cliente impersonalizado.
SECURITY_IDENTIFICATION

Indica el nivel de "Identification" para un cliente impersonalizado.

SECURITY_IMPERSONATION

Indica el nivel de "Impersonation" para un cliente impersonalizado.

SECURITY_DELEGATION

Indica el nivel de "Delegation" para un cliente impersonalizado.

SECURITY_CONTEXT_TRACKING

Especifica que el modo de seguimiento dinámico para la seguridad. Si este flag no se especifica, el modo de seguimiento para la seguridad será estático.

SECURITY_EFFECTIVE_ONLY

Especifica que sólo los aspectos de contexto de seguridad del cliente especificados están disponibles para el servidor. Si no se especifica este flag, todos los aspectos del contexto de seguridad del cliente estarán disponibles.

Este flag permite al cliente limitar los grupos y privilegios que un servidor puede usar mientras impersonaliza el cliente.

Ver seguridad* para mayor información.

hTemplateFile: especifica un manipulador con acceso GENERIC_READ a un fichero que se usará como plantilla. El fichero plantilla suministra los atributos para el fichero que se creará..

Valor de retorno

Si la función tiene éxito, el valor de retorno es un manipulador del fichero especificado abierto. Si el fichero especificado existe antes de la llamada a la función, y dwCreationDistribution es CREATE_ALWAYS o OPEN_ALWAYS, una llamad a GetLastError devolverá ERROR_ALREADY_EXISTS (siempre que la función haya tenido éxito). Si el fichero no existía antes de la llamada, GetLastError devuelve cero.

Si la función falla, el valor de retorno es INVALID_HANDLE_VALUE. Para obtener información adicional sobre el error, llamar a GetLastError.

Observaciones

Cuando se crea un fichero nuevo, la función CreateFile realiza las siguientes acciones:

  • Combina los atributos del fichero y los flags especificados por dwFlagsAndAttributes con FILE_ATTRIBUTE_ARCHIVE.
  • Hace la longitud del fichero igual a cero.
  • Copia los atributos extendidos suministrados por el fichero de plantilla al nuevo fichero, si se ha especificado el parámetro hTemplateFile.

Cuando se abre un fichero que ya existe, CreateFile realiza las siguientes acciones:

  • Combina los flags especificados por dwFlagsAndAttributes con los atributos del fichero existente. CreateFile ignora los atributos de fichero especificados por dwFlagsAndAttributes.
  • Modifica la longitud del fichero de acuerdo con el valor de dwCreationDistribution.
  • Ignora el parámetro hTemplateFile.
  • Ignora el miembro lpSecurityDescriptor de la estructura SECURITY_ATTRIBUTES si el parámetro lpSecurityAttributes no es NULL. Los otros miembros de la estructura son válidos. El miembro bInheritHandle es el único medio para indicar si el manipulador del fichero puede ser heredado.

Si CreateFile abre el cliente final de una tubería con nombre (named pipe), la función usa cualquier instancia de la tubería que esté en estado de escucha. El proceso de apertura puede duplicar el manipulador tantas veces como se requiera pero, una vez abierto, la instancia de la tubería con nombre no puede ser abierta por otro cliente. El acceso especificado cuando se abre la tubería debe ser compatible con el acceso especificado en el parámetro dwOpenMode de la función CreateNamedPipe. Para más información sobre tuberías, ver el tema de tuberías.

Si CreateFile abre el cliente final de un mailslot, la función siempre devuelve un manipulador válido, aunque el mailslot no exista. En otras palabras, no existe relación entre abrir un extremo cliente y abrir el extremo servidor de un mailslot. Para más información sobre mailslots, ver el tema de Mailslots.

CreateFile puede crear un manipulador para un recurso de comunicaciones, como el puerto serie COM1. Para recursos de comunicaciones, el parámetro dwCreationDistribution debe ser OPEN_EXISTING, y el parámetro hTemplate debe ser NULL. Pueden especificarse acceso de lectura, escritura o lectura-escritura, y el manipulador puede ser abierto para I/O superpuestas (overlapped). Para más información sobre comunicaciones, ver el tema de Comunicaciones.

CreateFile puede crear un manipulador para entrada de consola (CONIN$). Si el proceso posee un manipulador abierto a él como resultado de herencia o duplicación, también podrá crear un manipulador al buffer de la pantalla activa (CONOUT$).

El proceso que llama debe ser adjuntado a una consola heredada o a una asignada mediante la función AllocConsole. Para manipuladores de consola, poner los parámetros de CreateFile como sigue:

Parámetro Valor
lpFileName

Usar el valor CONIN$ para especificar la entrada de consola y el valor CONOUT$ para especificar la salida de consola.

CONIN$ toma un manipulador del buffer de entrada de la consola, incluso si la función SetStdHandle redirige el manipulador de la entrada estándar. Para tomar el manipulador de la entrada estándar, usar la función GetStdHandle.

CONOUT$ toma un manipulador del buffer de la pantalla activa, aunque SetStdHandle redirija el manipulador de la salida estándar. Para tomar el manipulador de la salida estándar, usar GetStdHandle.

dwDesiredAccess

Es preferible GENERIC_READ | GENERIC_WRITE, pero cualquiera puede limitar el acceso.

dwShareMode

Si el proceso que llama hereda la consola o si un proceso hijo debe poder acceder a la consola, este parámetro debe ser FILE_SHARE_READ | FILE_SHARE_WRITE.

lpSecurityAttributes

Si quieres que la consola pueda ser heredada, el miembro bInheritHandle de la estructura SECURITY_ATTRIBUTES debe ser TRUE.

dwCreationDistribution

El usuario debe especificar OPEN_EXISTING cuando use CreateFile para abrir la consola.

dwFlagsAndAttributes

Ignorado.

hTemplateFile Ignorado.

La lista siguiente muestra los efectos de varios valores de fwdAccess y lpFileName.

lpFileName fwdAccess Resultado
CON GENERIC_READ Abre la consola para entrada.
CON GENERIC_WRITE Abre la consola para salida.
CON GENERIC_READ\
GENERIC_WRITE
Windows 95: Hace que CreateFile falle; GetLastError devolverá ERROR_PATH_NOT_FOUND.
Windows NT: Hace que CreateFile falle; GetLastError devolverá ERROR_FILE_NOT_FOUND.

Se puede usar CreateFile para abrir un dispositivo de disco o una partición de un disco. La función devuelve un manipulador al dispositivo de disco; este manipulador puede ser usado con la función DeviceIOControl. Los siguientes requisitos deben ser cumplidos para que la llamada tenga éxito:

  • El proceso que llame debe tener privilegios de administrador para que la operación funcione en un disco duro.
  • La cadena lpFileName debe tener el formato \\.\PHYSICALDRIVEx para abrir el disco duro x. Los números de los miembros disco empiezan en cero. Por ejemplo:
Cadena Significado
\\.\PHYSICALDRIVE2

Obtiene un manipulador al tercer disco físico en el ordenador del usuario.

  • La cadena lpFileName debe tener la forma \\.\x: para abrir la unidad del disco flexible x o una partición x de un disco duro. Por ejemplo:
Cadena Significado
\\.\A: Obtiene un manipulador de la unidad A del ordenador del usuario.
\\.\C: Obtiene un manipulador de la unidad C del ordenador del usuario.

Windows 95: esta técnica no funciona para operar con unidades lógicas. En Windows 95, especificar una cadena de esta forma hace que CreateFile retorne un error.

  • El parámetro dwCreationDistribution debe tener el valor OPEN_EXISTING.

  • Cuando se abre un disco flexible o una partición de un disco duro, se debe especificar el flag FILE_SHARE_WRITE en el parámetro dwShareMode.

La función CloseHandle se usa para cerrar el manipulador devuelto por CreateFile.

Como se comentó antes, especificar cero para dwDesiredAccess permite a una aplicación consultar los atributos del dispositivo sin acceder al dispositivo. Este tipo de consulta es corriente, por ejemplo, si una aplicación quiere determinar el tamaño de un disco flexible y los formatos que soporta sin tener un disquete en la unidad.

También se ha comentado que si una aplicación abre un fichero con FILE_FLAG_NO_BUFFERING, las direcciones de los buffer para operaciones de lectura y escritura deben ser alineadas en direcciones de memoria que sean múltiplos enteros del tamaño del sector del volumen. Un modo de hacer esto es usar VirtualAlloc para asignar el buffer. La función VirtualAlloc asigna memoria que está alienada en direcciones que son múltiplos enteros del tamaño de la página de memoria del sistema operativo. Como ambos, la página de memoria y el tamaño del sector del volumen son potencias de 2, y las páginas de memoria son más grandes que los sectores del volumen, las direcciones de memoria estarán también alineadas según múltiplos enteros del tamaño del sector del volumen.

Una aplicación no puede crear un directorio mediante CreateFile; debe llamar a CreateDirectory o a CreateDirectoryEx para ello.

Windows NT: se puede obtener un manipulador a un directorio activando el flag FILE_FLAG_BACKUP_SEMANTICS. Un manipulador de directorio puede ser pasado a ciertas funciones Win32 en lugar de un manipulador de fichero.

Alguno sistemas de ficheros, como NTFS, soportan compresión para ficheros individuales y directorios. En volúmenes formateados para este sistema de ficheros, un nuevo directorio heredará el atributo de compresión de su directorio padre.