cvs: phpdoc-ca /chapters streams.structs.xml streams.xml

From:	Bernat Foj Capell	Date:	Mon, 08 Aug 2005 17:15:25 +0000
Subject:	cvs: phpdoc-ca /chapters streams.structs.xml streams.xml
Groups:	php.doc.ca
Request:	Send a blank email to doc-ca+get-56@lists.php.net to get a copy of this message

jabro Mon Aug 8 13:15:25 2005 EDT Added files: /phpdoc-ca/chapters streams.structs.xml streams.xml Log: initial translation

http://cvs.php.net/co.php/phpdoc-ca/chapters/streams.structs.xml?r=1.1&p=1 Index: phpdoc-ca/chapters/streams.structs.xml +++ phpdoc-ca/chapters/streams.structs.xml <?xml version="1.0" encoding="iso-8859-1"?>    <reference id="streams.structs"> <title>Estructures de corrents</title> <refentry id="streams.struct-php-stream-statbuf"> <refnamediv> <refname>struct php_stream_statbuf</refname> <refpurpose>Reté informació sobre un fitxer o URL</refpurpose> </refnamediv> <refsect1> <title>Descripció</title> <synopsis> <structname>php_stream_statbuf</structname> <type>struct stat</type> <structfield>sb</structfield> </synopsis> <para> <structfield>sb</structfield> és un estat d'estructura definit pel sistema i regular. </para> </refsect1> </refentry> <refentry id="streams.struct-php-stream-dirent"> <refnamediv> <refname>struct php_stream_dirent</refname> <refpurpose>Reté informació sobre un fitxer durant l'escaneig del directori</refpurpose> </refnamediv> <refsect1> <title>Descripció</title> <synopsis> <structname>php_stream_dirent</structname> <type>char</type> <structfield>d_name[MAXPATHLEN]</structfield> </synopsis> <para> <structfield>d_name</structfield> reté el nom del fitxer, relatiu al directori que s'està escanejant. </para> </refsect1> </refentry> <refentry id="streams.struct-php-stream-ops"> <refnamediv> <refname>struct php_stream_ops</refname> <refpurpose>Reté funcions membres per a la implementació del corrent</refpurpose> </refnamediv> <refsect1> <title>Description</title> <programlisting role="c"> <![CDATA[ typedef struct _php_stream_ops { /* tots els corrents HAN d'implementar aquestes operacions */ size_t (*write)(php_stream *stream, const char *buf, size_t count TSRMLS_DC); size_t (*read)(php_stream *stream, char *buf, size_t count TSRMLS_DC); int (*close)(php_stream *stream, int close_handle TSRMLS_DC); int (*flush)(php_stream *stream TSRMLS_DC); const char *label; /* nom que descrigui aquest tipus de corrent */ /* aquestes operacions són opcionals, i es poden definir com a NULL si el corrent no * suporta una operació en particular */ int (*seek)(php_stream *stream, off_t offset, int whence TSRMLS_DC); char *(*gets)(php_stream *stream, char *buf, size_t size TSRMLS_DC); int (*cast)(php_stream *stream, int castas, void **ret TSRMLS_DC); int (*stat)(php_stream *stream, php_stream_statbuf *ssb TSRMLS_DC); } php_stream_ops; ]]> </programlisting> </refsect1> </refentry> <refentry id="streams.struct-php-stream-wrapper"> <refnamediv> <refname>struct php_stream_wrapper</refname> <refpurpose>Reté les propietats de l'embolcall i apunta a les operacions</refpurpose> </refnamediv> <refsect1> <title>Descripció</title> <programlisting role="c"> <![CDATA[ struct _php_stream_wrapper { php_stream_wrapper_ops *wops; /* operacions que l'embolcall pot realitzar */ void *abstract; /* context per a l'embolcall */ int is_url; /* per tal que PG(allow_url_fopen) es pugui respectar */ /* suport per als embolcalls per a tornar (múltiples) missatges d'error a l'obridor de corrent */ int err_count; char **err_stack; } php_stream_wrapper; ]]> </programlisting> </refsect1> </refentry> <refentry id="streams.struct-php-stream-wrapper-ops"> <refnamediv> <refname>struct php_stream_wrapper_ops</refname> <refpurpose>Reté funcions membres per a la implementació de l'embolcall de corrent</refpurpose> </refnamediv> <refsect1> <title>Descripció</title> <programlisting role="c"> <![CDATA[ typedef struct _php_stream_wrapper_ops { /* obre/crea un corrent embolcallat */ php_stream *(*stream_opener)(php_stream_wrapper *wrapper, char *filename, char *mode, int options, char **opened_path, php_stream_context *context STREAMS_DC TSRMLS_DC); /* tanca/destrueix un corrent embolcallat */ int (*stream_closer)(php_stream_wrapper *wrapper, php_stream *stream TSRMLS_DC); /* estat d'un corrent embolcallat */ int (*stream_stat)(php_stream_wrapper *wrapper, php_stream *stream, php_stream_statbuf *ssb TSR$ /* estat d'un URL */ int (*url_stat)(php_stream_wrapper *wrapper, char *url, php_stream_statbuf *ssb TSRMLS_DC); /* obre un corrent de "directori" */ php_stream *(*dir_opener)(php_stream_wrapper *wrapper, char *filename, char *mode, int options, char **opened_path, php_stream_context *context STREAMS_DC TSRMLS_DC); const char *label; /* Suprimeix/desenllaça un fitxer */ int (*unlink)(php_stream_wrapper *wrapper, char *url, int options, php_stream_context *context TSRMLS_DC); } php_stream_wrapper_ops; ]]> </programlisting> </refsect1> </refentry> <refentry id="streams.struct-php-stream-filter"> <refnamediv> <refname>struct php_stream_filter</refname> <refpurpose>Reté propietats de filtre i apunta a les operacions</refpurpose> </refnamediv> <refsect1> <title>Descripció</title> <programlisting role="c"> <![CDATA[ struct _php_stream_filter { php_stream_filter_ops *fops; void *abstract; /* per usar per la implementació del filtre */ php_stream_filter *next; php_stream_filter *prev; int is_persistent; /* enllaç a corrent i cadena */ php_stream_filter_chain *chain; /* galledes (buckets) en memòria intermitja */ php_stream_bucket_brigade buffer; } php_stream_filter; ]]> </programlisting> </refsect1> </refentry> <refentry id="streams.struct-php-stream-filter-ops"> <refnamediv> <refname>struct php_stream_filter_ops</refname> <refpurpose>Reté funcions membres per a la implementació d'un filtre de corrent</refpurpose> </refnamediv> <refsect1> <title>Descripció</title> <programlisting role="c"> <![CDATA[ typedef struct _php_stream_filter_ops { php_stream_filter_status_t (*filter)( php_stream *stream, php_stream_filter *thisfilter, php_stream_bucket_brigade *buckets_in, php_stream_bucket_brigade *buckets_out, size_t *bytes_consumed, int flags TSRMLS_DC); void (*dtor)(php_stream_filter *thisfilter TSRMLS_DC); const char *label; } php_stream_filter_ops; ]]> </programlisting> </refsect1> </refentry> </reference>  http://cvs.php.net/co.php/phpdoc-ca/chapters/streams.xml?r=1.1&p=1 Index: phpdoc-ca/chapters/streams.xml +++ phpdoc-ca/chapters/streams.xml <?xml version="1.0" encoding="iso-8859-1"?>    <chapter id="streams"> <title>API de corrents de dades per a autors d'extensions php</title> <sect1 id="streams.overview"> <title>Introducció</title> <para> L'API de corrents de dades del PHP introdueix una aproximació unificada a la gestió de fitxers i sòcols en una extensió PHP. Utilitzant una sola API amb funcions estàndard per a operacions comunes, l'API de corrents permet a la vostra extensió accedir a fitxers, sòcols, URLs, memòria i objectes definits per seqüències. La de corrents és una API extensible en temps d'execució que permet a mòduls carregats dinàmicament (i a seqüències!) registrar nous corrents. </para> <para> La finalitat de l'API de corrents és fer confortable als desenvolupadors l'obertura de fitxers, URLs i altres fonts de dades que es poden passar per corrents amb una API unificada que és fàcil d'entendre. L'API està més o menys basada en la família de funcions C stdio ANSI (amb semàntica idèntica per a la major part de les funcions principals), així que els programadors C tindran un sentiment de familiaritat amb els corrents. </para> <para> L'API de corrents opera en un parell de nivells diferents: al nivell base, l'API defineix objectes php_stream per a representar fonts de dades que es poden passar per corrents. En un nivell una mica superior, l'API defineix objectes php_stream_wrapper amb "embolcalls" al voltant del nivell inferior de l'API per a proveir suport per a la recuperació de dades i metadades dels URLs. Un paràmetre addicional <literal>context</literal>, acceptat per la major part de les funcions de creació de corrents, és passat al mètode de l'embolcall <literal>stream_opener</literal> per a definir adientment el comportament de l'embolcall. </para> <para> Qualsevol corrent, un cop obert, pot tenir qualsevol nombre de <literal>filtres</literal> aplicats, els qual processen dades com si es llegeixen de o s'escriuen a un corrent. </para> <para> Els corrents es poden convertir (cast) en altres tipus de gestors de fitxers, de tal forma que es poden usar amb biblioteques de tercers sense grans problemes. Això permet a aquestes biblioteques accedir a dades directament de fonts URL. Si el vostre sistema té les funcions <function>fopencookie</function> o <function>funopen</function>, podeu fins i tot passar qualsevol corrent PHP a qualsevol biblioteca que utilitzi stdio ANSI! </para> <para> <note> <para> Les funcions d'aquest capítol són per utilitzar al codi font del PHP i no són funcions PHP. Funcions de corrent d'usuaris es poden trobar a la <link linkend="ref.stream">Referència de corrents</link>. </para> </note> </para> </sect1> <sect1 id="streams.basics"> <title>Principis de corrents de dades</title> <para> Utilitzar corrents s'assembla molt a utilitzar funcions stdio ANSI. La diferència principal és el com s'obté el gestor de corrent per a començar. En la majoria de casos, utilitzareu <function>php_stream_open_wrapper</function> per a obtenir un gestor de corrent. Aquesta funció funciona molt semblantment a fopen, tal i com podem veure a l'exemple següent: </para> <para> <example> <title>exemple simple de corrent que mostra la pàgina principal del PHP</title> <programlisting role="c"> <![CDATA[ php_stream * stream = php_stream_open_wrapper("http://www.php.net", "rb", REPORT_ERRORS, NULL); if (stream) { while(!php_stream_eof(stream)) { char buf[1024]; if (php_stream_gets(stream, buf, sizeof(buf))) { printf(buf); } else { break; } } php_stream_close(stream); } ]]> </programlisting> </example> </para> <para> La taula de sota us mostra els equivalents pels corrents de les funcions stdio ANSI més corrents. Si no s'indica una altra cosa, les semàntiques de les funcions són idèntiques. <table> <title>Funcions stdio ANSI equivalents a l'API de corrents</title> <tgroup cols="3"> <thead> <row> <entry>Funció Stdio ANSI</entry> <entry>Funció de corrent PHP</entry> <entry>Notes</entry> </row> </thead> <tbody> <row> <entry>fopen</entry> <entry>php_stream_open_wrapper</entry> <entry>Els corrents inclouen un paràmetre addicional</entry> </row> <row> <entry>fclose</entry> <entry>php_stream_close</entry> <entry></entry> </row> <row> <entry>fgets</entry> <entry>php_stream_gets</entry> <entry></entry> </row> <row> <entry>fread</entry> <entry>php_stream_read</entry> <entry>El paràmetre nmemb s'assumeix com que té valor 1, per tant el prototipus és més semblant a read(2)</entry> </row> <row> <entry>fwrite</entry> <entry>php_stream_write</entry> <entry>El paràmetre nmemb s'assumeix com que té valor 1, per tant el prototipus és més semblant a write(2)</entry> </row> <row> <entry>fseek</entry> <entry>php_stream_seek</entry> <entry></entry> </row> <row> <entry>ftell</entry> <entry>php_stream_tell</entry> <entry></entry> </row> <row> <entry>rewind</entry> <entry>php_stream_rewind</entry> <entry></entry> </row> <row> <entry>feof</entry> <entry>php_stream_eof</entry> <entry></entry> </row> <row> <entry>fgetc</entry> <entry>php_stream_getc</entry> <entry></entry> </row> <row> <entry>fputc</entry> <entry>php_stream_putc</entry> <entry></entry> </row> <row> <entry>fflush</entry> <entry>php_stream_flush</entry> <entry></entry> </row> <row> <entry>puts</entry> <entry>php_stream_puts</entry> <entry>La mateixa semàntica que puts, NO fputs</entry> </row> <row> <entry>fstat</entry> <entry>php_stream_stat</entry> <entry>Els corrents tenen una estructura d'estat més rica</entry> </row> </tbody> </tgroup> </table> </para> </sect1> <sect1 id="streams.resources"> <title>Corrents de dades com a recursos</title> <para> Tots els corrents es registren com a recursos quan es creen. Això assegura que es netejaran adequadament àdhuc si hi ha algun tipus d'error fatal. Totes les funcions de sistemes de fitxers a PHP operen amb recursos de corrents - això vol dir que les vostres extensions poden acceptar punters de fitxer PHP regulars com a paràmetres, i retornar corrents des de les seves funcions. L'API de corrents fa aquest procés tan simple com és possible: </para> <para> <example> <title>Com acceptar un corrent com a paràmetre</title> <programlisting role="c"> <![CDATA[ PHP_FUNCTION(example_write_hello) { zval *zstream; php_stream *stream; if (FAILURE == zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "r", &zstream)) return; php_stream_from_zval(stream, &zstream); /* ara podeu usar el corrent. De totes formes, no "posseïu" el corrent, és de la seqüència. Això vol dir que vós NO HEU de tancar el corrent, perquè això farà estrellar el PHP! */ php_stream_write(stream, "hello\n"); RETURN_TRUE(); } ]]> </programlisting> </example> </para> <para> <example> <title>Com retornar un corrent des d'una funció</title> <programlisting role="c"> <![CDATA[ PHP_FUNCTION(example_open_php_home_page) { php_stream *stream; stream = php_stream_open_wrapper("http://www.php.net", "rb", REPORT_ERRORS, NULL); php_stream_to_zval(stream, return_value); /* després d'aquest punt, el propietari del corrent és la seqüència. Si el tanqueu ara, estrellareu el PHP! */ } ]]> </programlisting> </example> </para> <para> Atès que els corrents es netejen automàticament, és temptador pensar que ho podem resoldre sent programadors descuidats i no preocupant-nos de tancar els corrents quan hem acabat amb ells. Tot i que això podria funcionar, no és una bona idea per un cert nombre de raons: els corrents retenen recursos del sistema mentre estan oberts, així que deixar un fitxer obert després que hagueu acabat podria impedir a altres processos d'accedir-hi . Si una seqüència tracta un gran nombre de fitxers, l'acumulació de recursos usats, tant en termes de memòria i del pur nombre de fitxers oberts, podria fer que les peticions en un servidor web fallessin. Sona malament, oi? L'API de corrents inclou una mica de màgia que us ajudarà a mantenir el vostre codi net - si un corrent no és tancat pel vostre codi quan hauria de ser-ho, trobareu alguna informació de depuració útil al vostre registre d'errors del servidor. </para> <note> <simpara> Utilitzeu sempre un muntatge de depurat del PHP quan desenvolupeu una extensió (<option>--enable-debug</option> quan executeu el configure), ja que s'ha fet un gran esforç per advertir-vos de pèrdues de memòria i corrents. </simpara> </note> <para> En alguns casos, és útil mantenir un corrent obert durant la duració d'una petició, per actuar com a registre o seguir les traces d'un fitxer, per exemple. Escriure el codi per a netejar amb seguretat un corrent d'aquests no és difícil, però són diverses línies de codi que no són estrictament necessàries. Per estalviar-vos la molèstia d'escriure el codi, podeu marcar un corrent com a que està d'acord amb la neteja automàtica. El que això significa és que l'API de corrents no emetrà un avís quan sigui l'hora de netejar automàticament un corrent. Per a fer això, podeu usar <function>php_stream_auto_cleanup</function>. </para> </sect1> </chapter> &chapters.streams.common; &chapters.streams.dir; &chapters.streams.file; &chapters.streams.socket; &chapters.streams.structs; &chapters.streams.constants;