Función CreateMailslotA (winbase.h)

Artículo
03/08/2023

Crea un mailslot con el nombre especificado y devuelve un identificador que un servidor mailslot puede usar para realizar operaciones en el objeto mailslot. Mailslot es local en el equipo que lo crea. Se produce un error si ya existe un mailslot con el nombre especificado.

Sintaxis

HANDLE CreateMailslotA(
  [in]           LPCSTR                lpName,
  [in]           DWORD                 nMaxMessageSize,
  [in]           DWORD                 lReadTimeout,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parámetros

[in] lpName

Nombre del mailslot. Este nombre debe tener el siguiente formato:

\\.\mailslot\[path]name

El campo de nombre debe ser único. El nombre puede incluir varios niveles de pseudo directorios separados por barras diagonales inversas. Por ejemplo, ambos \\.\mailslot\example_mailslot_name y \\.\mailslot\abc\def\ghi son nombres válidos.

[in] nMaxMessageSize

Tamaño máximo de un único mensaje que se puede escribir en el mailslot, en bytes. Para especificar que el mensaje puede tener cualquier tamaño, establezca este valor en cero.

[in] lReadTimeout

La hora en que una operación de lectura puede esperar a que se escriba un mensaje en el mailslot antes de que se produzca un tiempo de espera, en milisegundos. Los valores siguientes tienen significados especiales.

Valor	Significado
0	Devuelve inmediatamente si no hay ningún mensaje presente. (El sistema no trata una devolución inmediata como un error).
MAILSLOT_WAIT_FOREVER ((DWORD)-1)	Espera para siempre un mensaje.

Este valor de tiempo de espera se aplica a todas las operaciones de lectura posteriores y a todos los identificadores heredados de mailslot.

[in, optional] lpSecurityAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES . El miembro bInheritHandle de la estructura determina si los procesos secundarios pueden heredar el identificador devuelto. Si lpSecurityAttributes es NULL, no se puede heredar el identificador.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador para el mailslot, para su uso en las operaciones mailslot del servidor. El identificador devuelto por esta función es asincrónico o superpuesto.

Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.

Comentarios

El mailslot existe hasta que se cumple una de las siguientes condiciones:

El último identificador (posiblemente heredado o duplicado) se cierra mediante la función CloseHandle .
El proceso propietario del último identificador (posiblemente heredado o duplicado) se cierra.

El sistema usa el segundo método para destruir los gráficos de correo.

Para escribir un mensaje en un mailslot, un proceso usa la función CreateFile , especificando el nombre de mailslot mediante uno de los siguientes formatos.

Formato	Uso
\\.\mailslot\name	Recupera un identificador de cliente en un mailslot local.
\\nombreDeEquipo\mailslot\name	Recupera un identificador de cliente en un mailslot remoto.
\\domainname\mailslot\name	Recupera un identificador de cliente para todos los gráficos de correo con el nombre especificado en el dominio especificado.
\\\mailslot\name*	Recupera un identificador de cliente para todos los gráficos de correo con el nombre especificado en el dominio principal del sistema.

Si CreateFile especifica un dominio o usa el formato asterisco para especificar el dominio principal del sistema, la aplicación no puede escribir más de 424 bytes a la vez en el mailslot. Si la aplicación intenta hacerlo, se produce un error en la función WriteFile y GetLastError devuelve ERROR_BAD_NETPATH.

Una aplicación debe especificar la marca FILE_SHARE_READ al usar CreateFile para recuperar un identificador de cliente en un mailslot.

Si se llama a CreateFile para acceder a un mailslot inexistente, se establecerá el código de error de ERROR_FILE_NOT_FOUND .

Ejemplos

Para obtener un ejemplo, consulte Creación de un objeto Mailslot.

Nota

El encabezado winbase.h define CreateMailslot como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll