28.3. Interfaces client

28.3.1. Cr�er un objet large

La fonction

Oid lo_creat(PGconn *conn, int mode);

cr�e un nouvel objet large. mode est un masque d�crivant les diff�rents attributs du nouvel objet. Les constantes symboliques utilis�es ici sont d�finies dans le fichier d'en-t�te libpq/libpq-fs.h. Le type d'acc�s (lecture, �criture ou les deux) est contr�l� par une combinaison OU des bits INV_READ et INV_WRITE. Les 16 bits de poids faible du masque ont �t� utilis�s historiquement � Berkeley pour d�signer le num�ro du gestionnaire de stockage sur lequel l'objet large devrait r�sider. Ces bits devraient toujours �tre � z�ro maintenant. (Le type d'acc�s ne fait r�ellement rien de plus mais un ou deux des bits doivent �tre configur�s pour �viter une erreurs.) La valeur de retour est l'OID assign� au nouvel objet large ou InvalidOid (z�ro) en cas d'erreur.

Un exemple :

inv_oid = lo_creat(conn, INV_READ|INV_WRITE);

28.3.2. Importer un objet large

Pour importer un fichier du syst�me d'exploitation en tant qu'objet large, appelez

Oid lo_import(PGconn *conn, const char *filename);

filename sp�cifie le nom du fichier � importer comme objet large. Le code de retour est l'OID assign� au nouvel objet large ou InvalidOid (zero) en cas d'�chec. Notez que le fichier est lu par la biblioth�que d'interface du client, pas par le serveur. Donc il doit exister dans le syst�me de fichier du client et lisible par l'application du client.

28.3.3. Exporter un objet large

Pour exporter un objet large en tant que fichier du syst�me d'exploitation, appelez

int lo_export(PGconn *conn, Oid lobjId, const char *filename);

L'argument lobjId sp�cifie l'OID de l'objet large � exporter et l'argument filename sp�cifie le nom du fichier. Notez que le fichier est �crit par la biblioth�que d'interface du client, pas par le serveur. Renvoie 1 en cas de succ�s, -1 en cas d'�chec.

28.3.4. Ouvrir un objet large existant

Pour ouvrir un objet large existant pour lire ou �crire, appelez

int lo_open(PGconn *conn, Oid lobjId, int mode);

L'argument lobjId sp�cifie l'OID de l'objet large � ouvrir. Les bits mode contr�lent si l'objet est ouvert en lecture (INV_READ), �criture (INV_WRITE) ou les deux. Un objet large ne peut pas �tre ouvert avant d'avoir �t� cr��. lo_open renvoie un descripteur (positif) d'objet large pour une utilisation future avec lo_read, lo_write, lo_lseek, lo_tell et lo_close. Le descripteur est uniquement valide pour la dur�e de la transaction en cours. En cas d'�chec, -1 est renvoy�.

28.3.5. �crire des donn�es dans un objet large

La fonction

int lo_write(PGconn *conn, int fd, const char *buf, size_t len);

�crit len octets de buf dans le descripteur fd de l'objet large. L'argument fd doit avoir �t� renvoy� par un appel pr�c�dent � lo_open. Le nombre d'octets r�ellement �crits est renvoy�. Dans le cas d'une erreur, une valeur n�gative est renvoy�e.

28.3.6. Lire des donn�es � partir d'un objet large

La fonction

int lo_read(PGconn *conn, int fd, char *buf, size_t len);

lit len octets du descripteur de l'objet large fd et les place dans buf. L'argument fd doit avoir �t� renvoy� par un appel pr�c�dent � lo_open. Le nombre d'octets r�ellement lus est renvoy�. Dans le cas d'une erreur, une valeur n�gative est renvoy�e.

28.3.7. Recherche dans un objet large

Pour modifier l'emplacement courant de lecture ou �criture associ� au descripteur d'un objet large, appelez

int lo_lseek(PGconn *conn, int fd, int offset, int whence);

Cette fonction d�place le pointeur d'emplacement courant pour le descripteur de l'objet large identifi� par fd au nouvel emplacement sp�cifi� avec le d�calage (offset). Les valeurs valides pour whence sont SEEK_SET (rechercher depuis le d�but de l'objet), SEEK_CUR (rechercher depuis la position courante) et SEEK_END (rechercher depuis la fin de l'objet). Le code de retour est le nouvel emplacement du pointeur ou -1 en cas d'erreur.

28.3.8. Obtenir la position de recherche d'un objet large

Pour obtenir la position actuelle de lecture ou �criture d'un descripteur d'objet large, appelez

int lo_tell(PGconn *conn, int fd);

S'il y a une erreur, le code de retour est n�gatif.

28.3.9. Fermer un descripteur d'objet large

Un descripteur d'objet large peut �tre ferm� en appelant

int lo_close(PGconn *conn, int fd);

o� fd est un descripteur d'objet large renvoy� par lo_open. En cas de succ�s, lo_close renvoie z�ro. Renvoie 1 en cas de succ�s, -1 en cas d'�chec.

Tous les descripteurs d'objets larges restant ouverts � la fin d'une transaction seront automatiquement ferm�s.

28.3.10. Supprimer un objet large

Pour supprimer un objet large de la base de donn�es, appelez

int lo_unlink(PGconn *conn, Oid lobjId);

L'argument lobjId sp�cifie l'OID de l'objet large � supprimer. Dans le cas d'une erreur, le code de retour est n�gatif.