BSerialPort

Hérite de: aucun

Déclaré dans: be/device/SerialPort.h

Bibliothèque: libdevice.so

Sommaire

Un objet BSerialPort représente une connexion série RS-232 pour l'ordinateur. A travers les fonctions de BSerialPort, vous pouvez lire les données reçues par un port série et écrire les données à travers la connexion. Vous pouvez aussi configurer la connexion pour, par exemple, initialiser le nombre de données et bits d'arrêt, déterminer la fréquence à laquelle les données seront envoyées et reçues, et sélectionner le type de contrôle de flux (matériel ou logiciel) qui devra être utilisé.

Pour lire et écrire les données, un objet BSerialPort doit d'abord ouvrir un des ports série par nom. Pour trouver les noms de tous les ports série sur l'ordinateur, utilisez les fonctions: CountDevices() et GetDeviceName()

   BSerialPort serial;
   char devName[B_OS_NAME_LENGTH];
   int32 n = 0;
   
   for (int32 n = serial.CountDevices()-1; n >= 0; n--) {
      serial.GetDeviceName(n, devName);
   
      if ( serial.Open(devName) > 0 ) 
          ....
   }

L'objet BSerialPort communique avec le driver pour le port qu'il a d'ouvert. Le driver gère un tableau d'entrées pour collecter les données entrantes et un petit tableau de sorties pour conserver les données sortantes. Quand l'objet lira et écrira des données, il lira à partir de, et écrira vers, ces tableaux.

Les drivers de port série, et donc les objets BSerialPort, envoient et reçoivent seulement des données asynchrones.

Constructeur et Destructeur

BSerialPort()

	BSerialPort(void)

Initialise l'objet BSerialPort avec les valeurs par défaut suivantes:

• Contrôle de flux matériel (voir SetFlowControl())

• Une fréquence de donnée de 19,200 bits par seconde (voir SetDataRate())

• Une unité série avec 8 bits de données, 1 bit d'arrêt, et pas de parité (voir SetDataBits())

• Arrêt sans limite de temps—et un temps hors délai infini—pour lire les données (voir Read())

Le nouvel objet ne représente pas de port série particulier. Après la construction, il est nécessaire d'ouvrir un des ports par nom.

Le type de flux de contrôle doit être choisi avant qu'un port ne soit ouvert. Mais les autres initialisations par défaut listées ci-dessus peuvent être changées avant ou après l'ouverture d'un port.

Voir aussi: Open()

~BSerialPort()

	virtual ~BSerialPort()

S'assure que le port est fermé avant que l'objet ne soit détruit.

Fonctions Membres

ClearInput() , ClearOutput()

	void ClearInput(void) void ClearOutput(void)

Ces fonctions vident les tableaux d'entrées et de sorties du driver de port série, de façon à ce que le contenu du tableau d'entrées ne soit pas lu (par la fonction Read() ) et que le contenu du tableau de sorties (après avoir été écrit par Write()) ne soit pas transmis à travers la connexion.

Les tableaux sont effacés automatiquement quand un port est ouvert.

Voir aussi: Read(), Write(), Open()

Close() voir Open()

DataBits() voir SetDataBits()

IsCTS()

	bool IsCTS(void)

Retourne true si la broche Clear to Send (CTS) (Effacer à Envoyer) est validée, et false sinon.

IsDCD()

	bool IsDCD(void)

Retourne true si la broche Data Carrier Detect (DCD) (Détection de Retenue de Donnée) est validée, et false sinon.

IsDSR()

	bool IsDSR(void)

Retourne true si la broche Data Set Ready (DSR) (Prêt pour Initialisation de Donnée) est validée, et false sinon.

IsRI()

	bool IsRI(void)

Retourne true si la broche Ring Indicator (RI) (Indicateur d'Anneau) est validée, et false sinon.

Open() , Close()

	status_t Open(const char *name) void Close(void)

Ces fonctions ouvrent le port série name et le ferme aussitôt. Pour obtenir un nom de port de série, utilisez la fonction GetDeviceName(); un exemple est montré dans l'introduction .

Pour être capable de lire et d'écrire une donnée, l'objet BSerialPort doit avoir un port ouvert. Il peut ouvrir d'abord un port puis un autre, mais il ne peut pas avoir plus d'un port ouvert en même temps. S'il a déjà un port ouvert quand Open() est appelée, ce port est fermé avant qu'un essai ne soit effectué pour ouvrir le port name. (Ainsi, à la fois Open() et Close() ferment le port ouvert courant.)

Open() ne peut ouvrir le port name si une autre entité l'a déjà ouvert. (Si BSerialPort lui-même a déjà name ouvert, Open() le ferme d'abord, puis le réouvre à nouveau.)

Quand un port série est ouvert, ses tableaux d'entrées et sorties sont vidés et la broche Data Terminal Ready (DTR) (Terminal de Donnée Prêt) est validée.

CODES DE RETOUR

entiers positifs (pas 0). Succès.

• B_PERMISSION_DENIED. Le port est déjà ouvert.

ParityMode() voir SetDataBits()

Read() , SetBlocking() , SetTimeout()

	ssize_t Read(void *buffer, size_t maxBytes) void SetBlocking(bool shouldBlock) status_t SetTimeout(bigtime_t timeout)

Read() prend la donnée entrante depuis le driver de port série et la place dans le tableau de données buffer fourni. En aucun cas il ne sera lu plus de maxBytes—une valeur qui devra refléter la capacité du tableau buffer. Le tableau d'entrées du driver, à partir duquel Read() prend les données, contient un maximum de 2,024 octets (2048 sur le matériel Mac). Cette fonction échoue si l'objet BSerialPort n'a pas de port ouvert.

Le nombre d'octets que Read() lira avant de se terminer ne dépend pas seulement de maxBytes, mais aussi du drapeau shouldBlock et du timeout initialisé par les deux autres fonctions.

• SetBlocking() détermine si Read() devrait s'arrêter et attendre que maxBytes données soient arrivées au port série si ce nombre n'est pas déjà disponible en lecture. Si le drapeau shouldBlock est true, Read() bloquera. Cependant, si shouldBlock est false, Read() prendra autant d'octets qui attendent d'être lus, jusqu'au maximum demandé, puis se terminera immédiatement. Si aucune donnée n'attend au port série, il se termine sans rien lire.

  L'initialisation par défaut de shouldBlock est true.

• SetTimeout() initialise un temps limite sur la durée où Read() bloquera en attendant que la donnée arrive au tableau d'entrées du port. timeout est en rapport avec Read() seulement si le drapeau shouldBlock est true. Cependant, le temps limite s'applique aussi à la fonction WaitForInput() , qui bloque toujours, quelque soit l'initialisation de shouldBlock.

  Il n'y a pas de temps limite si timeout est initialisé à B_INFINITE_TIMEOUT — Read() (et WaitForInput()) bloquera indéfiniment. Autrement, timeout est exprimé en microsecondes et peut aller d'un minimum de 100,000 (0.1 second) jusqu'à un maximum de 25,500,000 (25.5 secondes); les différences de moins de 100,000 microsecondes ne sont pas reconnues; elles sont arrondies au centième de seconde le plus proche.

CODES DE RETOUR

Read() retourne...

• un entier positif ou nul. Succès; la valeur est le nombre d'octets qui ont été lus.

CODES DE RETOUR

SetTimeout() retourne...

• B_OK. Succès.

SetBlocking() voir Read()

SetDataBits() , SetStopBits() , SetParityMode() , DataBits() , StopBits() , ParityMode() , data_bits , stop_bits , parity_mode

	void SetDataBits(data_bits count) void SetStopBits(stop_bits count) data_bits DataBits(void) stop_bits StopBits(void) typedef enum { B_DATA_BITS_7, B_DATA_BITS_8 } data_bits typedef enum { B_STOP_BITS_1, B_STOP_BITS_2 } stop_bits

Ces fonctions intialisent et retournent les caractéristiques de l'unité série utilisée pour envoyer et recevoir des données.

• SetDataBits() initialise le nombre de bits de données dans chaque unité; par défaut c'est B_DATA_BITS_8.

• SetStopBits() initialise le nombre de bits d'arrêt dans chaque unité; par défaut c'est B_STOP_BITS_2.

• SetParityMode() initialise si l'unité série contient un bit de parité et, si c'est le cas, le type de parité utilisé; par défaut c'est B_NO_PARITY.

SetDataRate() , DataRate() , data_rate

	status_t SetDataRate(data_rate bitsPerSecond) data_rate DataRate(void)

Ces fonctions initialisent et retournent la fréquence (en bits par seconde) à laquelle les données sont à la fois transmises et reçues.

La fréquence de données par défaut est B_19200_BPS. Si la fréquence est initialisée à 0 (B_0_BPS), les données seront envoyées et reçues en un nombre indéterminé de bits par seconde.

CODES DE RETOUR

SetDataRate() retourne...

• B_OK. La fréquence a été initialisée avec succès.

SetDTR()

	status_t SetDTR(bool pinAsserted)

Valide la broche Data Terminal Ready (DTR) (Terminal de Données Prêt) si le drapeau pinAsserted est true, et l'invalide si le drapeau est false. La fonction devrait toujours retourner B_OK.

SetFlowControl() , FlowControl()

	void SetFlowControl(uint32 mask) uint32 FlowControl(void)

Ces fonctions initialisent et retournent le type de contrôle de flux que le driver doit utiliser.Il y a quatre possibilités:

Code de Contrôle	Signification
B_SOFTWARE_CONTROL	Le contrôle est maintenu à travers les caractères XON et XOFF insérés dans le flot de données.
B_HARDWARE_CONTROL	Le contrôle est maintenu à travers les broches Clear to Send (CTS) (Effacer pour Envoyer) et Request to Send (RTS)(Demander pour Envoyer).
B_SOFTWARE_CONTROL + B_HARDWARE_CONTROL	Les deux du dessus.
0 (zero)	Pas de contrôle.

SetFlowControl() devrait être appelé avant qu'un port série spécifique ne soit ouvert. Vous ne pouvez pas changer le type de flux de contrôle que le driver utilise en milieu de (transmission de) flot.

SetParityMode() see SetDataBits()

SetRTS()

	status_t SetRTS(bool pinAsserted)

Valide la broche Request to Send (RTS)(Demander pour Envoyer) si le drapeau pinAsserted est true, et l'invalide si le drapeau est false. La fonction retourne toujours B_OK.

SetStopBits() voir SetDataBits()

SetTimeout() voir Read()

WaitForInput()

	ssize_t WaitForInput(void)

Attend que la donnée en entrée arrive sur le port série et retourne le nombre d'octets disponibles pour être lus. Si la donnée attend déjà, la fonction se termine immédiattement.

Cette fonction ne tient pas compte du drapeau initialisé par SetBlocking(); elle bloque même si blocking et mis à off pour la fonction Read() . Cependant, elle tient compte de timeout initialisé par SetTimeout(). Si le délai expire avant que les données soient arrivées au port série, elle retourne 0.

Write()

	ssize_t Write(const void *data, size_t numBytes)

Ecrit jusqu'à numBytes de données data dans le tableau de sortie du port série. Cette fonction réussira à écrire la donnée seulement si l'objet BSerialPort a un port ouvert. Le tableau de sortie contient un maximum de 512 ctets (1024 sur le matériel Mac).

CODES DE RETOUR

entier positif ou nul. Succés; la valeur est le nombre d'octets qui ont été écrits.

• B_INTERRUPTED. L'opération a été interrompue par un signal.