Função CreateMailslotA (winbase.h)

Artigo
11/20/2024

Cria um emaillot com o nome especificado e retorna um identificador que um servidor de emaillot pode usar para executar operações no emaillot. O emaillot é 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 emaillot. Esse nome deve ter o seguinte formulário:

\\.\mailslot\[caminho]nome

O campo de nome deve ser exclusivo. O nome pode incluir vários níveis de pseudodiretórios separados por barra invertida. 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 emaillot, 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 uma mensagem ser gravada 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 emaillot herdados.

[in, optional] lpSecurityAttributes

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

Valor de retorno

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

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

Observações

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

O último identificador (possivelmente herdado ou duplicado) a 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 emaillot usando um dos seguintes formatos.

Formato	Uso
\\.\mailslot\nome	Recupera um identificador de cliente para um emaillot local.
\\nome do computador\mailslot\nome	Recupera um identificador de cliente para um emaillot remoto.
\\nome de domínio\mailslot\nome	Recupera um identificador de cliente para todos os emailslots com o nome especificado no domínio especificado.
\\\mailslot\nome*	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 emaillot. Se o aplicativo tentar fazer isso, a função WriteFile falhará e GetLastError retornará ERROR_BAD_NETPATH.

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

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

Exemplos

Para obter um exemplo, consulte Criando umde Emaillot.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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