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:

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

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:

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

Cualquier combinación de los flags siguientes es aceptable.

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:

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:

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

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:

• 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:

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.