structure SERIAL_TIMEOUTS (ntddser.h)

Article
02/26/2024

La structure SERIAL_TIMEOUTS spécifie les paramètres de délai d’attente pour les opérations de lecture et d’écriture par le port série.

Syntaxe

typedef struct _SERIAL_TIMEOUTS {
  ULONG ReadIntervalTimeout;
  ULONG ReadTotalTimeoutMultiplier;
  ULONG ReadTotalTimeoutConstant;
  ULONG WriteTotalTimeoutMultiplier;
  ULONG WriteTotalTimeoutConstant;
} SERIAL_TIMEOUTS, *PSERIAL_TIMEOUTS;

Membres

ReadIntervalTimeout

Durée maximale, en millisecondes, autorisée entre deux octets consécutifs dans une opération de lecture. Opération de lecture qui dépasse ce délai maximal. Ce maximum ne s’applique pas à l’intervalle de temps qui précède la lecture du premier octet. La valeur zéro indique que les délais d’expiration d’intervalle ne sont pas utilisés. Pour plus d'informations, consultez la section Notes.

ReadTotalTimeoutMultiplier

Durée maximale, en millisecondes, autorisée par octet dans une opération de lecture. Opération de lecture qui dépasse ce délai maximal. Pour plus d’informations, consultez Remarques.

ReadTotalTimeoutConstant

Durée maximale, en millisecondes, autorisée par opération de lecture. Opération de lecture qui dépasse ce délai maximal. Pour plus d’informations, consultez Remarques.

WriteTotalTimeoutMultiplier

Durée totale maximale, en millisecondes, autorisée par octet dans une opération d’écriture. Opération d’écriture qui dépasse ce délai maximal. Pour plus d’informations, consultez Remarques.

WriteTotalTimeoutConstant

Durée maximale, en millisecondes, autorisée par opération d’écriture. Opération d’écriture qui dépasse ce délai maximal. Pour plus d’informations, consultez Remarques.

Remarques

La structure SERIAL_TIMEOUTS est utilisée par les demandes de contrôle d’E /S IOCTL_SERIAL_SET_TIMEOUTS et IOCTL_SERIAL_GET_TIMEOUTS . Une demande de contrôle d’E/S IOCTL_SERIAL_SET_TIMEOUTS utilise cette structure pour spécifier un ensemble de paramètres de délai d’attente pour le port série à utiliser pour les opérations de lecture et d’écriture. Une demande de contrôle d’E/S IOCTL_SERIAL_GET_TIMEOUTS utilise cette structure pour récupérer les paramètres de délai d’attente définis par la demande de IOCTL_SERIAL_SET_TIMEOUTS précédente.

Une demande de lecture ou d’écriture se termine correctement lorsque le nombre d’octets spécifié est transféré ou que l’opération de lecture ou d’écriture demandée expire. La requête retourne le code STATUS_SUCCESS status pour indiquer que le nombre d’octets spécifié a été transféré. La demande retourne le code STATUS_TIMEOUT status pour indiquer que l’opération a expiré.

Si une demande de IRP_MJ_READ spécifie une opération de lecture de longueur Ntₒtₐl octets, la durée maximale, Tmₐₓ, que le port série permet à l’opération de se terminer est calculée comme suit :

Tmₐₓ = Ntₒtₐl * ReadTotalTimeoutMultiplier + ReadTotalTimeoutConstant

Une demande de lecture qui dépasse ce maximum se termine lorsque le délai d’attente se produit et retourne le code STATUS_TIMEOUT status. Le champ Informations du bloc d’E/S status indique le nombre d’octets correctement lus avant le délai d’expiration.

Si une demande de IRP_MJ_WRITE spécifie une opération d’écriture de longueur Ntₒtₐl octets, la durée maximale, Tmₐₓ, que le port série permet à l’opération de se terminer est calculée comme suit :

Tmₐₓ = Ntₒtₐl * WriteTotalTimeoutMultiplier + WriteTotalTimeoutConstant

Une demande d’écriture qui dépasse ce maximum se termine lorsque le délai d’attente se produit et retourne le code STATUS_TIMEOUT status. Le champ Informations du bloc d’E/S status indique le nombre d’octets correctement écrits avant le délai d’expiration.

La durée maximale, Tmₐₓ, autorisée pour l’exécution d’une opération de lecture ou d’écriture est toujours mesurée à partir du moment où le port série démarre l’opération demandée, et non à partir du moment où le client envoie la demande.

Si ReadIntervalTimeout, ReadTotalTimeoutMultiplier et ReadTotalTimeoutConstant sont tous zéro, les opérations de lecture n’expirent jamais. Si WriteTotalTimeoutMultiplier et WriteTotalTimeoutConstant sont tous deux zéro, les opérations d’écriture n’expirent jamais.

Si ReadIntervalTimeout est égal à zéro, il n’existe aucun intervalle maximal entre les octets consécutifs dans les opérations de lecture, et les délais d’expiration sont basés uniquement sur les membres ReadTotalTimeoutMultiplier et ReadTotalTimeoutConstant .

Si ReadTotalTimeoutMultiplier et ReadTotalTimeoutConstant sont tous deux zéro et que ReadIntervalTimeout est inférieur à MAXULONG et supérieur à zéro, une opération de lecture expire uniquement si l’intervalle entre une paire d’octets reçus consécutivement dépasse ReadIntervalTimeout. Si ces trois valeurs de délai d’attente sont utilisées et que la mémoire tampon d’entrée du port série est vide lorsqu’une demande de lecture est envoyée au port, cette requête n’expire jamais tant qu’après que le port a reçu au moins un octet de nouvelles données.

Si ReadIntervalTimeout est défini sur MAXULONG et que ReadTotalTimeoutConstant et ReadTotalTimeoutMultiplier sont tous deux zéro, une demande de lecture se termine immédiatement avec les octets qui ont déjà été reçus, même si aucun octet n’a été reçu. Dans ce cas, la demande de lecture retourne le code STATUS_SUCCESS status.

Si ReadIntervalTimeout et ReadTotalTimeoutMultiplier sont tous deux définis sur MAXULONG et que ReadTotalTimeoutConstant a une valeur supérieure à zéro et inférieure à MAXULONG, une demande de lecture se comporte comme suit :

S’il existe des octets dans la mémoire tampon d’entrée du port série, la demande de lecture se termine immédiatement avec les octets qui se trouvent dans la mémoire tampon et retourne le code STATUS_SUCCESS status.
S’il n’y a pas d’octets dans la mémoire tampon d’entrée, le port série attend qu’un octet arrive, puis termine immédiatement la demande de lecture avec l’octet de données et retourne le code STATUS_SUCCESS status.
Si aucun octet n’arrive dans le délai spécifié par ReadTotalTimeoutConstant, la demande de lecture expire, définit le champ Informations du bloc d’E/S status sur zéro et retourne le code STATUS_TIMEOUT status.

Une requête IOCTL_SERIAL_SET_TIMEOUTS échoue et retourne une erreur INVALID_PARAMETER status code si ReadIntervalTimeout et ReadTotalTimeoutConstant sont tous deux définis sur MAXULONG.

Un délai d’attente d’intervalle de lecture peut être utilisé pour détecter la fin d’un flux de données entrant lorsque la longueur du flux de données n’est pas connue à l’avance. Si une demande de lecture utilise cette technique, une STATUS_TIMEOUT status code signifie généralement que la demande s’est terminée avec succès.

Un délai d’expiration de l’intervalle de lecture se produit lorsque l’intervalle entre les octets entrants dépasse la valeur ReadIntervalTimeout . Les intervalles de délai d’expiration sont mesurés par rapport à l’horloge système, et la précision de la mesure du délai d’expiration est limitée par la granularité de l’horloge système. Par conséquent, un délai d’expiration peut se produire entre une coche d’horloge système antérieure et une autre plus tard que l’intervalle de délai d’expiration spécifié, en fonction de l’endroit où exactement les heures de début et de fin de cet intervalle se situent entre les graduations de l’horloge système. Des délais d’expiration peuvent se produire même plus tard si le traitement de l’interruption de l’horloge système est retardé par l’interruption du traitement pour d’autres appareils. Si un intervalle de délai d’attente spécifié est proche ou inférieur à la période entre les cycles de l’horloge système, le délai d’expiration peut se produire immédiatement, sans délai.

Un moyen possible de mesurer plus précisément les intervalles de délai d’attente plus petits consiste à réduire le temps entre les cycles d’horloge du système, mais cela risque d’augmenter la consommation d’énergie. En outre, la réduction de la période d’horloge système peut ne pas obtenir de façon fiable une précision plus fine de l’horloge système, sauf si le traitement lié aux interruptions par les différents pilotes de la plateforme peut être garanti pour ne pas retarder le traitement des interruptions d’horloge système.

La structure SERIAL_TIMEOUTS est similaire à la structure COMMTIMEOUTS , qui est utilisée par les fonctions SetCommTimeouts et GetCommTimeouts en mode utilisateur.

Pour plus d’informations, consultez Définition des délais d’expiration de lecture et d’écriture pour un appareil série.