CreateMailslotA, fonction (winbase.h)

Article
08/27/2023

Crée un maillot avec le nom spécifié et retourne un handle qu’un serveur maillot peut utiliser pour effectuer des opérations sur le maillot. Le maillot est local sur l’ordinateur qui le crée. Une erreur se produit si un maillot portant le nom spécifié existe déjà.

Syntaxe

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

Paramètres

[in] lpName

Nom du maillot. Ce nom doit avoir la forme suivante :

\\.\mailslot\[chemin]name

Le champ de nom doit être unique. Le nom peut inclure plusieurs niveaux de pseudo-répertoires séparés par des barres obliques inverses. Par exemple, \\.\mailslot\example_mailslot_name et \\.\mailslot\abc\def\ghi sont des noms valides.

[in] nMaxMessageSize

Taille maximale d’un seul message qui peut être écrit dans le maillot, en octets. Pour spécifier que le message peut être de n’importe quelle taille, définissez cette valeur sur zéro.

[in] lReadTimeout

Heure à laquelle une opération de lecture peut attendre qu’un message soit écrit dans le maillot avant qu’un délai d’expiration ne se produise, en millisecondes. Les valeurs suivantes ont des significations spéciales.

Valeur	Signification
0	Retourne immédiatement si aucun message n’est présent. (Le système ne traite pas un retour immédiat comme une erreur.)
MAILSLOT_WAIT_FOREVER ((DWORD)-1)	Attend toujours un message.

Cette valeur de délai d’attente s’applique à toutes les opérations de lecture suivantes et à tous les handles de maillot hérités.

[in, optional] lpSecurityAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES . Le membre bInheritHandle de la structure détermine si le handle retourné peut être hérité par des processus enfants. Si lpSecurityAttributes a la valeur NULL, le handle ne peut pas être hérité.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle dans le maillot, à utiliser dans les opérations de maillot de serveur. Le handle retourné par cette fonction est asynchrone ou se chevauche.

Si la fonction échoue, la valeur de retour est INVALID_HANDLE_VALUE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Le maillot existe jusqu’à ce que l’une des conditions suivantes soit remplie :

Le dernier handle (éventuellement hérité ou dupliqué) est fermé à l’aide de la fonction CloseHandle .
Processus propriétaire des dernières sorties de handle (éventuellement héritées ou dupliquées).

Le système utilise la deuxième méthode pour détruire les mailslots.

Pour écrire un message dans un maillot, un processus utilise la fonction CreateFile , en spécifiant le nom du maillot à l’aide de l’un des formats suivants.

Format	Utilisation
\\.\mailslot\name	Récupère un handle client dans un maillot local.
\\computername\mailslot\name	Récupère un handle client dans un maillot distant.
\\domainname\mailslot\name	Récupère un handle client pour tous les mailslots avec le nom spécifié dans le domaine spécifié.
\\\mailslot\name*	Récupère un handle client pour tous les mailslots avec le nom spécifié dans le domaine principal du système.

Si CreateFile spécifie un domaine ou utilise le format astérisque pour spécifier le domaine principal du système, l’application ne peut pas écrire plus de 424 octets à la fois dans le maillot. Si l’application tente de le faire, la fonction WriteFile échoue et GetLastError retourne ERROR_BAD_NETPATH.

Une application doit spécifier l’indicateur FILE_SHARE_READ lors de l’utilisation de CreateFile pour récupérer un handle client dans un maillot.

Si CreateFile est appelé pour accéder à un maillot inexistant, le code d’erreur ERROR_FILE_NOT_FOUND est défini.

Exemples

Pour obtenir un exemple, consultez Création d’un maillot.

Notes

L’en-tête winbase.h définit CreateMailslot comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll