Função CreateMailslotA (winbase.h)

Artigo
03/13/2024

Cria um emaillot com o nome especificado e retorna um identificador que um servidor maillot pode usar para executar operações no maillot. O maillot é local para o computador que o cria. Ocorrerá um erro se já existir um emaillot com o nome especificado.

Sintaxe

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

Parâmetros

[in] lpName

O nome do maillot. Esse nome deve ter o seguinte formulário:

\\.\mailslot\[path]name

O campo nome deve ser exclusivo. O nome pode incluir vários níveis de pseudodiretórios separados por barras invertidas. Por exemplo, \\.\mailslot\example_mailslot_name e \\.\mailslot\abc\def\ghi são nomes válidos.

[in] nMaxMessageSize

O tamanho máximo de uma única mensagem que pode ser gravada no maillot, em bytes. Para especificar que a mensagem pode ser de qualquer tamanho, defina esse valor como zero.

[in] lReadTimeout

O tempo em que uma operação de leitura pode aguardar a gravação de uma mensagem no emaillot antes que ocorra um tempo limite, em milissegundos. Os valores a seguir têm significados especiais.

Valor	Significado
0	Retorna imediatamente se nenhuma mensagem estiver presente. (O sistema não trata um retorno imediato como um erro.)
MAILSLOT_WAIT_FOREVER ((DWORD)-1)	Espera para sempre por uma mensagem.

Esse valor de tempo limite se aplica a todas as operações de leitura subsequentes e a todos os identificadores de maillot herdados.

[in, optional] lpSecurityAttributes

Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . O membro bInheritHandle da estrutura determina se o identificador retornado pode ser herdado por processos filho. Se lpSecurityAttributes for NULL, o identificador não poderá ser herdado.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o maillot, para uso em operações de emaillot do servidor. O identificador retornado por essa função é assíncrono ou sobreposto.

Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Comentários

O maillot existe até que uma das seguintes condições seja verdadeira:

O último identificador (possivelmente herdado ou duplicado) para ele é fechado usando a função CloseHandle .
O processo que possui o último identificador (possivelmente herdado ou duplicado) sai.

O sistema usa o segundo método para destruir emailslots.

Para gravar uma mensagem em um emaillot, um processo usa a função CreateFile , especificando o nome do maillot usando um dos formatos a seguir.

Formatar	Uso
\\.\mailslot\name	Recupera um identificador de cliente para um emaillot local.
\\computername\mailslot\name	Recupera um identificador de cliente para um emaillot remoto.
\\domainname\mailslot\name	Recupera um identificador de cliente para todos os emailslots com o nome especificado no domínio especificado.
\\\mailslot\name*	Recupera um identificador de cliente para todos os emailslots com o nome especificado no domínio primário do sistema.

Se CreateFile especificar um domínio ou usar o formato asterisco para especificar o domínio primário do sistema, o aplicativo não poderá gravar mais de 424 bytes por vez no maillot. Se o aplicativo tentar fazer isso, a função WriteFile falhará e GetLastErrorretornará ERROR_BAD_NETPATH.

Um aplicativo deve especificar o sinalizador FILE_SHARE_READ ao usar CreateFile para recuperar um identificador de cliente para um maillot.

Se CreateFile for chamado para acessar um maillot inexistente, o código de erro ERROR_FILE_NOT_FOUND será definido.

Exemplos

Para obter um exemplo, consulte Criando um Emaillot.

Observação

O cabeçalho winbase.h define CreateMailslot como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll