cvs: phpdoc-ca /chapters streams.structs.xml streams.xml
[email protected] ("Bernat Foj Capell") Mon, 08 Aug 2005 17:15:25 -0000
| Newsgroups | php.doc.ca |
|---|---|
| Message-ID | <cvsjabro1123521325@cvsserver> |
--jabro1123521325
Content-Type: text/plain
jabro Mon Aug 8 13:15:25 2005 EDT
Added files:
/phpdoc-ca/chapters streams.structs.xml streams.xml
Log:
initial translation
--jabro1123521325
Content-Type: text/plain
Content-Disposition: attachment; filename="jabro-20050808131525.txt"
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"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.6 Maintainer: jabro Status: ready -->
<!-- Author: Wez Furlong <[email protected]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<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>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
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"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.10 Maintainer: jabro Status: ready -->
<!-- Author: Wez Furlong <[email protected]>
Please contact me before making any major amendments to the
content of this section. Splitting/Merging are fine if they are
required for php-doc restructuring purposes - just drop me a line
if you make a change (so I can update my local copy).
-->
<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;
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--jabro1123521325--