Ces routines permettent aux programmeurs C de
décrire des structures de données arbitraires de
manière indépendante de la machine. Les données pour
les appels de routines distantes (RPC) sont transmises de cette
manière.
Les prototypes ci-dessous sont déclarés dans
<rpc/xdr.h> et utilisent les types suivants :
typedef int bool_t;
typedef bool_t (*xdrproc_t)(XDR *, void *,...);
Pour la déclaration du type XDR, consultez
<rpc/xdr.h>.
bool_t xdr_array(XDR *xdrs, char **arrp, unsigned int *sizep,
unsigned int maxsize, unsigned int elsize,
xdrproc_t elproc);
- Une primitive de filtrage qui traduit les tables de longueur variable en
leur représentation externe correspondante. Le paramètre
arrp est l'adresse d'un pointeur sur la chaîne, tandis que
sizep est l'adresse du nombre d'éléments dans la
table. Ce nombre d'éléments ne peut pas excéder
maxsize. Le paramètre elsize est la taille
(sizeof) de chaque élément de la table, et
elproc est un filtre XDR de traduction entre la forme C des
éléments de la table et sa représentation externe.
Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_bool(XDR *xdrs, bool_t *bp);
- Une primitive de filtrage assurant la traduction entre les booléens
(entiers C) et leur représentation externe. Durant
l'encodage des données, ce filtre produit soit un 1 soit un
0. Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_bytes(XDR *xdrs, char **sp, unsigned int *sizep,
unsigned int maxsize);
- Une primitive de filtrage assurant la traduction entre des chaînes
d'un certain nombre d'octets et leur représentation externe. Le
paramètre sp est l'adresse du pointeur sur la chaîne.
La longueur de la chaîne est située à l'adresse
sizep. Les chaînes ne peuvent pas être plus longues
que maxsize. Cette routine renvoie 1 si elle réussit,
0 sinon.
bool_t xdr_char(XDR *xdrs, char *cp);
- Une primitive de filtrage assurant la traduction entre les
caractères C et leur représentation externe. Cette
routine renvoie 1 si elle réussit, 0 sinon.
Note : les caractères encodés ne sont pas
accolés, et occupent quatre octets chacun. Pour les tables de
caractères, il vaut mieux se tourner vers xdr_bytes(),
xdr_opaque() ou xdr_string().
void xdr_destroy(XDR *xdrs);
- Une macro invoquant la routine de destruction associée avec le flux
XDR, xdrs. La destruction entraîne habituellement la
libération de structures de données privées
associées avec le flux. Le comportement est indéfini si on
essaye d'utiliser xdrs après avoir invoqué
xdr_destroy().
bool_t xdr_double(XDR *xdrs, double *dp);
- Une primitive de filtrage assurant la traduction entre les
nombres C en double précision et leur
représentation externe. Cette routine renvoie 1 si elle
réussit, 0 sinon.
bool_t xdr_enum(XDR *xdrs, enum_t *ep);
- Une primitive de filtrage assurant la traduction entre les
énumérés C enum (en
réalité des entiers) et leur représentation externe.
Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_float(XDR *xdrs, float *fp);
- Une primitive de filtrage assurant la traduction entre les nombres
float C et leur représentation externe. Cette routine
renvoie 1 si elle réussit, 0 sinon.
void xdr_free(xdrproc_t proc, char *objp);
- Routine générique de libération. Le premier argument
est la routine XDR de l'objet à libérer. Le second argument
est un pointeur vers l'objet lui-même. Note : le pointeur
transmis à cette routine n'est pas libéré,
mais l'endroit où il pointe est libéré
(récursivement).
unsigned int xdr_getpos(XDR *xdrs);
- Une macro invoquant la routine de lecture de position associée avec
le flux XDR, xdrs. Cette fonction renvoie un entier non
signé, qui indique la position dans le flux XDR. Une
fonctionnalité appréciable serait que l'arithmétique
usuelle fonctionne avec ce nombre, mais tous les flux XDR ne le
garantissent pas.
long *xdr_inline(XDR *xdrs, int len);
- Une macro qui invoque la routine en ligne associée avec le flux XDR
xdrs. Cette routine renvoie un pointeur vers une portion continue
du tampon du flux. len est la longueur en octets du tampon
désiré. Note : le pointeur est converti en
long *.
- Attention : xdr_inline() peut renvoyer NULL (0) si elle ne
peut allouer une portion continue de tampon de la taille
réclamée. Ce comportement peut néanmoins varier d'une
instance de flux à l'autre ; elle existe par souci
d'efficacité.
bool_t xdr_int(XDR *xdrs, int *ip);
- Une primitive de filtrage assurant la traduction entre les
entiers C et leur représentation externe. Cette routine
renvoie 1 si elle réussit, 0 sinon.
bool_t xdr_long(XDR *xdrs, long *lp);
- Une primitive de filtrage assurant la traduction entre les entiers
long C et leur représentation externe. Cette routine
renvoie 1 si elle réussit, 0 sinon.
void xdrmem_create(XDR *xdrs, char *addr, unsigned int size,
enum xdr_op op);
- Cette routine initialise l'objet flux XDR pointé par xdrs.
Les données du flux sont lues ou écrites dans le bloc
mémoire situé en addr et dont la longueur ne
dépasse pas size octets. L'argument op
détermine la direction du flux XDR (XDR_ENCODE,
XDR_DECODE ou XDR_FREE).
bool_t xdr_opaque(XDR *xdrs, char *cp, unsigned int cnt);
- Une primitive de filtrage assurant la traduction entre des données
opaques de taille fixe et leur représentation externe. Le
paramètre cp est l'adresse de l'objet opaque, et cnt
est sa taille en octets. Cette routine renvoie 1 si elle
réussit, 0 sinon.
bool_t xdr_pointer(XDR *xdrs, char **objpp,
unsigned int objsize, xdrproc_t xdrobj);
- Comme xdr_reference() sauf qu'elle met bout à bout les
pointeurs NULL alors que xdr_reference() ne le fait pas. Ainsi
xdr_pointer() peut représenter des structures de
données récursives, comme les arbres binaires ou les listes
chaînées.
void xdrrec_create(XDR *xdrs, unsigned int sendsize,
unsigned int recvsize, char *handle,
int (*readit)(char *, char *, int),
int (*writeit)(char *, char *, int));
- Cette routine initialise le flux XDR pointé par xdrs. Les
données du flux sont écrites dans un tampon de taille
sendsize. Une valeur nulle indique que le système choisira
une taille adéquate. Les données du flux sont lues depuis un
tampon de taille recvsize. De même le système
choisira une taille adéquate en transmettant une valeur nulle.
Lorsque le tampon de sortie du flux est plein, la fonction writeit
est appelée. Symétriquement, lorsque le tampon
d'entrée est vide, la fonction readit est invoquée.
Le comportement de ces routines est similaire aux deux appels
système read(2) et write(2), sauf que le descripteur
handle est passé aux routines en tant que premier
paramètre. Note : l'attribut op du flux XDR doit
être défini par l'appelant.
- Attention : pour lire depuis un flux XDR créé par
cette API, il est nécessaire d'appeler d'abord
xdrrec_skiprecord() avant d'appeler d'autres API XDR. Cela
insère des octets additionnels dans le flux pour fournir des
informations de limites d'enregistrement. De plus des flux XDR
créés par des API xdr*_create différentes ne
sont pas compatibles pour la même raison.
bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);
- Cette routine ne peut être invoquée que sur des flux
créé par xdrrec_create(). Les données dans le
tampon de sortie sont considérées comme un enregistrement
complet, et le tampon de sortie est éventuellement écrit si
sendnow est non nul. Cette routine renvoie 1 si elle
réussit, 0 sinon.
bool_t xdrrec_eof(XDR *xdrs);
- Cette routine ne peut être invoqué que sur des flux
créés par xdrrec_create(). Après avoir rempli
le reste de l'enregistrement avec les données du flux, cette
routine renvoie 1 si le flux n'a plus de données
d'entrée, et 0 sinon.
bool_t xdrrec_skiprecord(XDR *xdrs);
- Cette routine ne peut être invoqué que sur des flux
créés par xdrrec_create(). Elle indique à
l'implémentation XDR que le reste de l'enregistrement en cours dans
le tampon d'entrée doit être éliminé. Cette
routine renvoie 1 si elle réussit, 0 sinon.
bool_t xdr_reference(XDR *xdrs, char **pp, unsigned int size,
xdrproc_t proc);
- Une primitive qui gère les pointeurs sur les structures. Le
paramètre pp est l'adresse du pointeur, size est la
taille (sizeof) de la structure pointée par *pp, et
proc est la procédure XDR qui filtre la structure entre sa
forme C et sa représentation externe. Cette routine renvoie
1 si elle réussit, et 0 sinon.
- Attention : cette routine ne comprend pas les pointeurs NULL.
Utilisez xdr_pointer() à sa place.
xdr_setpos(XDR *xdrs, unsigned int pos);
- Une macro qui invoque la routine de positionnement associée au flux
XDR xdrs. Le paramètre pos est une valeur de position
obtenue avec xdr_getpos(). Cette routine renvoie 1 si le
flux XDR peut être repositionné, et zéro sinon.
- Attention : il est difficile de repositionner certains types de
flux XDR, ce qui peut faire échouer cette routine avec certains
flux et réussir avec d'autres.
bool_t xdr_short(XDR *xdrs, short *sp);
- Une primitive de filtrage assurant la traduction entre les entiers
short C et leur représentation externe. Cette routine
renvoie 1 si elle réussit, 0 sinon.
void xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op);
- Cette routine initialise l'objet flux XDR pointé par xdrs.
Les données du flux XDR sont écrites dans — ou
lues depuis — le flux d'entrée-sortie standard
file. Le paramètre op détermine la direction
du flux XDR (XDR_ENCODE, XDR_DECODE ou
XDR_FREE).
- Attention : la routine de destruction associée avec un tel
flux XDR appelle fflush(3) sur le flux file, mais pas
fclose(3).
bool_t xdr_string(XDR *xdrs, char **sp, unsigned int maxsize);
- Une primitive de filtrage assurant la traduction entre les chaînes
de caractères C et leur représentation externe. Les
chaînes ne peuvent pas être plus longues que maxsize.
Note : sp est l'adresse du pointeur sur la chaîne.
Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_u_char(XDR *xdrs, unsigned char *ucp);
- Une primitive de filtrage assurant la traduction entre les
caractères unsigned du C et leur
représentation externe. Cette routine renvoie 1 si elle
réussit, 0 sinon.
bool_t xdr_u_int(XDR *xdrs, unsigned int *up);
- Une primitive de filtrage assurant la traduction entre les entiers
unsigned du C et leur représentation externe. Cette
routine renvoie 1 si elle réussit, 0 sinon.
bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);
- Une primitive de filtrage assurant la traduction entre les entiers
unsigned long du C et leur représentation externe.
Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);
- Une primitive de filtrage assurant la traduction entre les entiers
unsigned short du C et leur représentation externe.
Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_union(XDR *xdrs, enum_t *dscmp, char *unp,
const struct xdr_discrim *choices,
xdrproc_t defaultarm); /* peut être NULL */
- Une primitive de filtrage assurant la traduction entre une
union C avec discriminant et sa représentation
externe correspondante. Elle traduit d'abord le discriminant de l'union,
situé en dscmp. Le discriminant doit toujours être du
type enum_t. Ensuite, l'union située en unp est
traduite. Le paramètre choices est un pointeur sur une table
de structures xdr_discrim(). Chaque structure contient une paire
ordonnée [valeur, procédure]. Si le
discriminant de l'union est égal à la valeur
associée, alors la procédure est invoquée pour
traduire l'union. La fin de la table de structures xdr_discrim()
est indiquée par une routine de valeur NULL. Si le discriminant
n'est pas trouvé dans la table choices, alors la
procédure defaultarm est invoquée (si elle ne vaut
pas NULL). Cette routine renvoie 1 si elle réussit, 0
sinon.
bool_t xdr_vector(XDR *xdrs, char *arrp, unsigned int size,
unsigned int elsize, xdrproc_t elproc);
- Une primitive de filtrage assurant la traduction entre les tables de
longueur fixe, et leur représentation externe. Le paramètre
arrp est l'adresse du pointeur sur la table, tandis que size
est le nombre d'éléments dans la table. Le paramètre
elsize est la taille (sizeof) d'un élément de
la table, et elproc est un filtre XDR assurant la traduction entre
la forme C des éléments de la table et leur
représentation externe. Cette routine renvoie 1 si elle
réussit, 0 sinon.
bool_t xdr_void(void);
- Cette routine renvoie toujours 1. Elle peut être
passée aux routines RPC qui ont besoin d'une fonction en
paramètre alors que rien ne doit être fait.
bool_t xdr_wrapstring(XDR *xdrs, char **sp);
- Une primitive qui appelle xdr_string(xdrs, sp, MAXUN.UNSIGNED);
où MAXUN.UNSIGNED est la valeur maximale d'un entier non
signé. xdr_wrapstring() est pratique car la
bibliothèque RPC passe un maximum de deux routines XDR comme
paramètres, et xdr_string(), l'une des primitives les plus
fréquemment utilisées en requiert trois. Cette routine
renvoie 1 si elle réussit, 0 sinon.