CreateMailslotA, fonction (winbase.h)

Article
11/20/2024

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 le formulaire suivant :

\\.\mailslot\[chemin d’accès]nom

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 message unique pouvant ê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

L’heure à laquelle une opération de lecture peut attendre qu’un message soit écrit dans le maillot avant qu’un délai d’attente 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 bInheritHandle membre de la structure détermine si le handle retourné peut être hérité par les processus enfants. Si lpSecurityAttributes est NULL, le handle ne peut pas être hérité.

Valeur de retour

Si la fonction réussit, la valeur de retour est un handle vers 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’erreur étendues, appelez GetLastError.

Remarques

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

Le dernier handle (éventuellement hérité ou dupliqué) est fermé à l’aide de la fonction CloseHandle.
Le processus propriétaire des derniers handles (éventuellement hérités ou dupliqués) s’arrête.

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

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

Format	Usage
\\.\mailslot\nom	Récupère un handle client dans un maillot local.
\\nom d’ordinateur\mailslot\nom	Récupère un handle client vers un maillot distant.
\\nom de domaine\mailslot\nom	Récupère un handle client pour tous les mailslots portant le nom spécifié dans le domaine spécifié.
\\\mailslot\nom*	Récupère un handle client pour tous les mailslots portant 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 de 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 non existant, le code d’erreur ERROR_FILE_NOT_FOUND est défini.

Exemples

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

Note

L’en-tête winbase.h définit CreateMailslot comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll