Sophie

Sophie

distrib > Mandriva > 2008.1 > x86_64 > by-pkgid > 05cd670d8a02b2b4a0ffb1756f2e8308 > files > 11874

php-manual-zh-5.2.4-1mdv2008.1.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Creating Variables</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="PHP 手册"
HREF="index.html"><LINK
REL="UP"
TITLE="Zend API：深入 PHP 内核"
HREF="zend.html"><LINK
REL="PREVIOUS"
TITLE="Accepting Arguments"
HREF="zend.arguments.html"><LINK
REL="NEXT"
TITLE="Duplicating Variable Contents: The Copy Constructor"
HREF="zend.copy-constructor.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=UTF-8"></HEAD
><BODY
CLASS="sect1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP 手册</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="zend.arguments.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>章 46. Zend API：深入 PHP 内核</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="zend.copy-constructor.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="zend.variables"
>Creating Variables</A
></H1
><P
>&#13;   When exchanging data from your own extensions with PHP scripts, one
   of the most important issues is the creation of variables. This
   section shows you how to deal with the variable types that PHP
   supports.
  </P
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.overview"
>Overview</A
></H2
><P
>&#13;    To create new variables that can be seen "from the outside" by the
    executing script, you need to allocate a new <CODE
CLASS="envar"
>zval</CODE
>
    container, fill this container with meaningful values, and then
    introduce it to Zend's internal symbol table. This basic process
    is common to all variable creations: 
   </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_variable; 

/* allocate and initialize new container */
MAKE_STD_ZVAL(new_variable); 

/* set type and variable contents here, see the following sections */ 

/* introduce this variable by the name "new_variable_name" into the symbol table */
ZEND_SET_SYMBOL(EG(active_symbol_table), "new_variable_name", new_variable); 

/* the variable is now accessible to the script by using $new_variable_name */</PRE
></TD
></TR
></TABLE
><P
>&#13;    The macro <TT
CLASS="literal"
>MAKE_STD_ZVAL</TT
> allocates a new
    <CODE
CLASS="envar"
>zval</CODE
> container using <TT
CLASS="literal"
>ALLOC_ZVAL</TT
>
    and initializes it using <TT
CLASS="literal"
>INIT_ZVAL</TT
>. As
    implemented in Zend at the time of this writing,
    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>initializing</I
></SPAN
> means setting the reference
    count to <TT
CLASS="literal"
>1</TT
> and clearing the
    <CODE
CLASS="envar"
>is_ref</CODE
> flag, but this process could be extended
    later - this is why it's a good idea to keep using
    <TT
CLASS="literal"
>MAKE_STD_ZVAL</TT
> instead of only using
    <TT
CLASS="literal"
>ALLOC_ZVAL</TT
>. If you want to optimize for speed
    (and you don't have to explicitly initialize the
    <CODE
CLASS="envar"
>zval</CODE
> container here), you can use
    <TT
CLASS="literal"
>ALLOC_ZVAL</TT
>, but this isn't recommended because
    it doesn't ensure data integrity.
   </P
><P
>&#13;    <TT
CLASS="literal"
>ZEND_SET_SYMBOL</TT
> takes care of introducing the
    new variable to Zend's symbol table. This macro checks whether the
    value already exists in the symbol table and converts the new
    symbol to a reference if so (with automatic deallocation of the
    old <CODE
CLASS="envar"
>zval</CODE
> container). This is the preferred method
    if speed is not a crucial issue and you'd like to keep memory
    usage low.
   </P
><P
>&#13;    Note that <TT
CLASS="literal"
>ZEND_SET_SYMBOL</TT
> makes use of the Zend
    executor globals via the macro <TT
CLASS="literal"
>EG</TT
>. By
    specifying <TT
CLASS="literal"
>EG(active_symbol_table)</TT
>, you get access to the
    currently active symbol table, dealing with the active, local scope. The local
    scope may differ depending on whether the function was invoked from
    within a function.
   </P
><P
>&#13;    If you need to optimize for speed and don't care about optimal memory
    usage, you can omit the check for an existing variable with the same value and instead
    force insertion into the symbol table by using
    <A
HREF="zend-api.zend-hash-update.html"
><B
CLASS="function"
>zend_hash_update()</B
></A
>: 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_variable;

/* allocate and initialize new container */
MAKE_STD_ZVAL(new_variable);

/* set type and variable contents here, see the following sections */

/* introduce this variable by the name "new_variable_name" into the symbol table */
zend_hash_update(
    EG(active_symbol_table),
    "new_variable_name",
    strlen("new_variable_name") + 1,
    &#38;new_variable,
    sizeof(zval *),
    NULL
);</PRE
></TD
></TR
></TABLE
>
    This is actually the standard method used in most modules.
   </P
><P
>&#13;    The variables generated with the snippet above will always be of local
    scope, so they reside in the context in which the function has been called. To
    create new variables in the global scope, use the same method
    but refer to another symbol table: 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_variable;
     
// allocate and initialize new container
MAKE_STD_ZVAL(new_variable);

//
// set type and variable contents here
//

// introduce this variable by the name "new_variable_name" into the global symbol table
ZEND_SET_SYMBOL(&#38;EG(symbol_table), "new_variable_name", new_variable);</PRE
></TD
></TR
></TABLE
>
    The macro <TT
CLASS="literal"
>ZEND_SET_SYMBOL</TT
> is now being
    called with a reference to the main, global symbol table by referring
    <TT
CLASS="literal"
>EG(symbol_table)</TT
>.
   </P
><P
>&#13;    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Note:</I
></SPAN
> The <CODE
CLASS="envar"
>active_symbol_table</CODE
>
    variable is a pointer, but <CODE
CLASS="envar"
>symbol_table</CODE
> is not.
    This is why you have to use
    <TT
CLASS="literal"
>EG(active_symbol_table)</TT
> and
    <TT
CLASS="literal"
>&#38;EG(symbol_table)</TT
> as parameters to
    <TT
CLASS="literal"
>ZEND_SET_SYMBOL</TT
> - it requires a pointer.
   </P
><P
>&#13;    Similarly, to get a more efficient version, you can hardcode the
    symbol table update: 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_variable;

// allocate and initialize new container
MAKE_STD_ZVAL(new_variable);

//
// set type and variable contents here
//

// introduce this variable by the name "new_variable_name" into the global symbol table
zend_hash_update(
    &#38;EG(symbol_table),
    "new_variable_name",
    strlen("new_variable_name") + 1,
    &#38;new_variable,
    sizeof(zval *),
    NULL
);</PRE
></TD
></TR
></TABLE
>
    <A
HREF="zend.variables.html#example.variable-scopes"
>例 46-9</A
> shows a sample source that
    creates two variables - <CODE
CLASS="envar"
>local_variable</CODE
> with a local scope
    and <CODE
CLASS="envar"
>global_variable</CODE
> with a global scope (see Figure 9.7). 
    The full example can be found on the CD-ROM.
   </P
><P
>&#13;    Note: You can see that the global variable is actually not accessible from
    within the function. This is because it's not imported into the local scope
    using <TT
CLASS="literal"
>global $global_variable;</TT
> in the PHP source. 
   </P
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="example.variable-scopes"
></A
><P
><B
>例 46-9. Creating variables with different scopes.</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>ZEND_FUNCTION(variable_creation)
{
    zval *new_var1, *new_var2;

    MAKE_STD_ZVAL(new_var1);
    MAKE_STD_ZVAL(new_var2);

    ZVAL_LONG(new_var1, 10);
    ZVAL_LONG(new_var2, 5);

    ZEND_SET_SYMBOL(EG(active_symbol_table), "local_variable", new_var1);
    ZEND_SET_SYMBOL(&#38;EG(symbol_table), "global_variable", new_var2);

    RETURN_NULL();

}</PRE
></TD
></TR
></TABLE
><P
><IMG
SRC="figures/zendapi.zend.06-variable-creation.png"></P
></DIV
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.long"
>Longs (Integers)</A
></H2
><P
>Now let's get to the assignment of data to variables, starting with
    longs. Longs are PHP's integers and are very simple to store. Looking at
    the <CODE
CLASS="envar"
>zval.value</CODE
> container structure discussed earlier in this
    chapter, you can see that the long data type is directly contained in the union,
    namely in the <CODE
CLASS="envar"
>lval</CODE
> field. The corresponding 
    <CODE
CLASS="envar"
>type</CODE
> value for longs is <TT
CLASS="literal"
>IS_LONG</TT
> 
    (see <A
HREF="zend.variables.html#example.create-long"
>例 46-10</A
>). 
    <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="example.create-long"
></A
><P
><B
>例 46-10. Creation of a long.</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_long;

MAKE_STD_ZVAL(new_long);

new_long-&#62;type = IS_LONG;
new_long-&#62;value.lval = 10;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
    Alternatively, you can use the macro <TT
CLASS="literal"
>ZVAL_LONG</TT
>:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_long;

MAKE_STD_ZVAL(new_long);
ZVAL_LONG(new_long, 10);</PRE
></TD
></TR
></TABLE
>
   </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.float"
>Doubles (Floats)</A
></H2
><P
>&#13;    Doubles are PHP's floats and are as easy to assign as longs, because their value
    is also contained directly in the union. The member in the 
    <CODE
CLASS="envar"
>zval.value</CODE
> container is <CODE
CLASS="envar"
>dval</CODE
>; 
    the corresponding type is <TT
CLASS="literal"
>IS_DOUBLE</TT
>. 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_double;

MAKE_STD_ZVAL(new_double);

new_double-&#62;type = IS_DOUBLE;
new_double-&#62;value.dval = 3.45;</PRE
></TD
></TR
></TABLE
>
    Alternatively, you can use the macro <TT
CLASS="literal"
>ZVAL_DOUBLE</TT
>:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_double;

MAKE_STD_ZVAL(new_double);
ZVAL_DOUBLE(new_double, 3.45);</PRE
></TD
></TR
></TABLE
>
   </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.string"
>Strings</A
></H2
><P
>&#13;    Strings need slightly more effort. As mentioned earlier, all strings
    that will be associated with Zend's internal data structures need to be
    allocated using Zend's own memory-management functions. Referencing of static
    strings or strings allocated with standard routines is not allowed. To assign
    strings, you have to access the structure <CODE
CLASS="envar"
>str</CODE
> in
    the <CODE
CLASS="envar"
>zval.value</CODE
> container. The corresponding type
    is <TT
CLASS="literal"
>IS_STRING</TT
>:
<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_string;
char *string_contents = "This is a new string variable";

MAKE_STD_ZVAL(new_string);

new_string-&#62;type = IS_STRING;
new_string-&#62;value.str.len = strlen(string_contents);
new_string-&#62;value.str.val = estrdup(string_contents);</PRE
></TD
></TR
></TABLE
>
    Note the usage of Zend's <B
CLASS="function"
>estrdup()</B
> here.
    Of course, you can also use the predefined macro
    <TT
CLASS="literal"
>ZVAL_STRING</TT
>:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_string;
char *string_contents = "This is a new string variable";

MAKE_STD_ZVAL(new_string);
ZVAL_STRING(new_string, string_contents, 1);</PRE
></TD
></TR
></TABLE
>
    <TT
CLASS="literal"
>ZVAL_STRING</TT
> accepts a third parameter that
    indicates whether the supplied string contents should be duplicated (using
    <B
CLASS="function"
>estrdup()</B
>). Setting this parameter
    to <TT
CLASS="literal"
>1</TT
> causes the string to be
    duplicated; <TT
CLASS="literal"
>0</TT
> simply uses the supplied pointer for the
    variable contents. This is most useful if you want to create a new variable
    referring to a string that's already allocated in Zend internal memory.
   </P
><P
>&#13;    If you want to truncate the string at a certain position or you
    already know its length, you can use <TT
CLASS="literal"
>ZVAL_STRINGL(zval,
     string, length, duplicate)</TT
>, which accepts an explicit
    string length to be set for the new string. This macro is faster
    than <TT
CLASS="literal"
>ZVAL_STRING</TT
> and also binary-safe.
   </P
><P
>&#13;    To create empty strings, set the string length to <TT
CLASS="literal"
>0</TT
> and
    use <TT
CLASS="literal"
>empty_string</TT
> as contents: 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>new_string-&#62;type = IS_STRING;
new_string-&#62;value.str.len = 0;
new_string-&#62;value.str.val = empty_string;</PRE
></TD
></TR
></TABLE
>
    Of course, there's a macro for this as
    well (<TT
CLASS="literal"
>ZVAL_EMPTY_STRING</TT
>):
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>MAKE_STD_ZVAL(new_string);
ZVAL_EMPTY_STRING(new_string);</PRE
></TD
></TR
></TABLE
>
   </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.boolean"
>Booleans</A
></H2
><P
>&#13;    Booleans are created just like longs, but have the
    type <TT
CLASS="literal"
>IS_BOOL</TT
>. Allowed values in
    <CODE
CLASS="envar"
>lval</CODE
> are <TT
CLASS="literal"
>0</TT
> and <TT
CLASS="literal"
>1</TT
>:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_bool;

MAKE_STD_ZVAL(new_bool);

new_bool-&#62;type = IS_BOOL;
new_bool-&#62;value.lval = 1;</PRE
></TD
></TR
></TABLE
>
    The corresponding macros for this type
    are <TT
CLASS="literal"
>ZVAL_BOOL</TT
> (allowing specification of the value) as well
    as <TT
CLASS="literal"
>ZVAL_TRUE</TT
> and <TT
CLASS="literal"
>ZVAL_FALSE</TT
> (which
    explicitly set the value to <TT
CLASS="literal"
>TRUE</TT
> and <TT
CLASS="literal"
>FALSE</TT
>,
    respectively).
   </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.array"
>Arrays</A
></H2
><P
>&#13;    Arrays are stored using Zend's internal hash tables, which can be
    accessed using the <B
CLASS="function"
>zend_hash_*()</B
> API. For every
    array that you want to create, you need a new hash table handle,
    which will be stored in the <CODE
CLASS="envar"
>ht</CODE
> member of the
    <CODE
CLASS="envar"
>zval.value</CODE
> container.
   </P
><P
>&#13;    There's a whole API solely for the creation of arrays, which is extremely
    handy. To start a new array, you call
    <A
HREF="zend-api.array-init.html"
><B
CLASS="function"
>array_init()</B
></A
>. 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_array;

MAKE_STD_ZVAL(new_array);

array_init(new_array);</PRE
></TD
></TR
></TABLE
>
    <A
HREF="zend-api.array-init.html"
><B
CLASS="function"
>array_init()</B
></A
> always returns <TT
CLASS="literal"
>SUCCESS</TT
>.
   </P
><P
>&#13;    To add new elements to the array, you can use numerous functions,
    depending on what you want to do. 
    <A
HREF="zend.variables.html#tab.api-assoc-arrays"
>表 46-8</A
>,
    <A
HREF="zend.variables.html#tab.api-indexed-arrays"
>表 46-9</A
> and
    <A
HREF="zend.variables.html#tab.api-indexed-array-2"
>表 46-10</A
>
    describe these functions. All functions return
    <TT
CLASS="literal"
>FAILURE</TT
> on failure and
    <TT
CLASS="literal"
>SUCCESS</TT
> on success.
   </P
><DIV
CLASS="table"
><A
NAME="tab.api-assoc-arrays"
></A
><P
><B
>表 46-8. Zend's API for Associative Arrays</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="1*"
TITLE="col2"><TBODY
><TR
><TD
>Function</TD
><TD
>Description</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_assoc_long(zval *array, char *key, long n);()</B
>
        </TD
><TD
>Adds an element of type <TT
CLASS="literal"
>long</TT
>.</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_assoc_unset(zval *array, char *key);()</B
></TD
><TD
>Adds an unset element.</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_assoc_bool(zval *array, char *key, int b);()</B
>
        </TD
><TD
>Adds a Boolean element.</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_assoc_resource(zval *array, char *key, int r);()</B
>
        </TD
><TD
>Adds a resource to the array.</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_assoc_double(zval *array, char *key, double d);()</B
>
        </TD
><TD
>Adds a floating-point value.</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_assoc_string(zval *array, char *key, char *str, int duplicate);()</B
>
        </TD
><TD
>&#13;         Adds a string to the array. The
         flag <CODE
CLASS="envar"
>duplicate</CODE
> specifies whether the string contents have to be
         copied to Zend internal memory.
        </TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>&#13;          add_assoc_stringl(zval *array, char *key, char *str, uint length, int duplicate);
         ()</B
>
        </TD
><TD
>&#13;         Adds a string with the desired length <CODE
CLASS="envar"
>length</CODE
>
         to the array. Otherwise, behaves like
         <A
HREF="zend-api.add-assoc-string.html"
><B
CLASS="function"
>add_assoc_string()</B
></A
>.
        </TD
></TR
><TR
><TD
><B
CLASS="function"
>add_assoc_zval(zval *array, char *key, zval *value);()</B
></TD
><TD
>Adds a zval to the array.  Useful for adding other arrays, objects, streams, etc...</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="table"
><A
NAME="tab.api-indexed-arrays"
></A
><P
><B
>表 46-9. Zend's API for Indexed Arrays, Part 1</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="1*"
TITLE="col2"><TBODY
><TR
><TD
>Function</TD
><TD
>Description</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_long(zval *array, uint idx, long
          n);()</B
></TD
><TD
>Adds an element of type <TT
CLASS="literal"
>long</TT
>.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_unset(zval *array, uint
          idx);()</B
></TD
><TD
>Adds an unset element.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_bool(zval *array, uint idx, int
          b);()</B
></TD
><TD
>Adds a Boolean element.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_resource(zval *array, uint idx, int
          r);()</B
></TD
><TD
>Adds a resource to the array.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_double(zval *array, uint idx, double
          d);()</B
></TD
><TD
>Adds a floating-point value.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_string(zval *array, uint idx, char
          *str, int duplicate);()</B
></TD
><TD
>Adds a string to the array. The
         flag <CODE
CLASS="envar"
>duplicate</CODE
> specifies whether the string contents have to be
         copied to Zend internal memory.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_stringl(zval *array, uint idx, char
          *str, uint length, int duplicate);()</B
></TD
><TD
>Adds a string with the desired
         length <CODE
CLASS="envar"
>length</CODE
> to the array. This function is faster and binary-safe. Otherwise, behaves like <A
HREF="zend-api.add-index-string.html"
><B
CLASS="function"
>add_index_string()</B
></A
>.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_index_zval(zval *array, uint idx, zval *value);()</B
></TD
><TD
>Adds a zval to the array.  Useful for adding other arrays, objects, streams, etc...</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="table"
><A
NAME="tab.api-indexed-array-2"
></A
><P
><B
>表 46-10. Zend's API for Indexed Arrays, Part 2</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="1*"
TITLE="col2"><TBODY
><TR
><TD
>Function</TD
><TD
>Description</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_long(zval *array, long
          n);()</B
></TD
><TD
>Adds an element of type <TT
CLASS="literal"
>long</TT
>.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_unset(zval
          *array);()</B
></TD
><TD
>Adds an unset element.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_bool(zval *array, int
          b);()</B
></TD
><TD
>Adds a Boolean element.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_resource(zval *array, int
          r);()</B
></TD
><TD
>Adds a resource to the array.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_double(zval *array, double
          d);()</B
></TD
><TD
>Adds a floating-point value.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_string(zval *array, char *str,
          int duplicate);()</B
></TD
><TD
>Adds a string to the array. The
         flag <CODE
CLASS="envar"
>duplicate</CODE
> specifies whether the string contents have to be
         copied to Zend internal memory.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_stringl(zval *array, char *str,
          uint length, int duplicate);()</B
></TD
><TD
>Adds a string with the desired
         length <CODE
CLASS="envar"
>length</CODE
> to the array. This function is faster and binary-safe. Otherwise, behaves like <A
HREF="zend-api.add-index-string.html"
><B
CLASS="function"
>add_index_string()</B
></A
>.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_next_index_zval(zval *array, zval *value);()</B
></TD
><TD
>Adds a zval to the array.  Useful for adding other arrays, objects, streams, etc...</TD
></TR
></TBODY
></TABLE
></DIV
><P
>&#13;    All these functions provide a handy abstraction to Zend's internal hash
    API. Of course, you can also use the hash functions directly - for example, if
    you already have a <CODE
CLASS="envar"
>zval</CODE
> container allocated that you want to 
    insert into an array. This is done using <A
HREF="zend-api.zend-hash-update.html"
><B
CLASS="function"
>zend_hash_update()</B
></A
>
    for associative arrays (see <A
HREF="zend.variables.html#example.array-add-assoc"
>例 46-11</A
>) and 
    <A
HREF="zend-api.zend-hash-index-update.html"
><B
CLASS="function"
>zend_hash_index_update()</B
></A
> for indexed arrays 
    (see <A
HREF="zend.variables.html#example.array-add-indexed"
>例 46-12</A
>): 
    <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="example.array-add-assoc"
></A
><P
><B
>例 46-11. Adding an element to an associative array.</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_array, *new_element;
char *key = "element_key";
      
MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);

array_init(new_array);

ZVAL_LONG(new_element, 10);

if(zend_hash_update(new_array-&#62;value.ht, key, strlen(key) + 1, (void *)&#38;new_element, sizeof(zval *), NULL) == FAILURE)
{
    // do error handling here
}</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
> 
    <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="example.array-add-indexed"
></A
><P
><B
>例 46-12. Adding an element to an indexed array.</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_array, *new_element;
int key = 2;

MAKE_STD_ZVAL(new_array);
MAKE_STD_ZVAL(new_element);

array_init(new_array);

ZVAL_LONG(new_element, 10);

if(zend_hash_index_update(new_array-&#62;value.ht, key, (void *)&#38;new_element, sizeof(zval *), NULL) == FAILURE)
{
    // do error handling here
}</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
   </P
><P
>&#13;    To emulate the functionality of
    <B
CLASS="function"
>add_next_index_*()</B
>, you can use this:
   </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zend_hash_next_index_insert(ht, zval **new_element, sizeof(zval *), NULL)</PRE
></TD
></TR
></TABLE
><P
>&#13;    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Note:</I
></SPAN
> To return arrays from a function, use <A
HREF="zend-api.array-init.html"
><B
CLASS="function"
>array_init()</B
></A
> and
    all following actions on the predefined variable <CODE
CLASS="envar"
>return_value</CODE
>
    (given as argument to your exported function; see the earlier discussion of the call interface). You do not have to use
    <TT
CLASS="literal"
>MAKE_STD_ZVAL</TT
> on this.
   </P
><P
>&#13;    <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>Tip:</I
></SPAN
> To avoid having to
    write <TT
CLASS="literal"
>new_array-&#62;value.ht</TT
> every time, you can
    use <TT
CLASS="literal"
>HASH_OF(new_array)</TT
>, which is also recommended for
    compatibility and style reasons.
   </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.object"
>Objects</A
></H2
><P
>&#13;    Since objects can be converted to arrays (and vice versa), you
    might have already guessed that they have a lot of similarities to
    arrays in PHP. Objects are maintained with the same hash
    functions, but there's a different API for creating them.
   </P
><P
>&#13;    To initialize an object, you use the
    function <A
HREF="zend-api.object-init.html"
><B
CLASS="function"
>object_init()</B
></A
>: 
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>zval *new_object;

MAKE_STD_ZVAL(new_object);

if(object_init(new_object) != SUCCESS)
{
    // do error handling here
}</PRE
></TD
></TR
></TABLE
>
    You can use the functions described in 
    <A
HREF="zend.variables.html#tab.object-creation"
>表 46-11</A
> 
    to add members to your object.
   </P
><DIV
CLASS="table"
><A
NAME="tab.object-creation"
></A
><P
><B
>表 46-11. Zend's API for Object Creation</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1.24*"
TITLE="col1"><COL
WIDTH="1*"
TITLE="col2"><TBODY
><TR
><TD
>Function</TD
><TD
>Description</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_long(zval *object, char *key, long
          l);()</B
></TD
><TD
>Adds a long to the object.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_unset(zval *object, char
          *key);()</B
></TD
><TD
>Adds an unset property to the object.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_bool(zval *object, char *key, int
          b);()</B
></TD
><TD
>Adds a Boolean to the object.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_resource(zval *object, char *key,
          long r);()</B
></TD
><TD
>Adds a resource to the object.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_double(zval *object, char *key,
          double d);()</B
></TD
><TD
>Adds a double to the object.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_string(zval *object, char *key,
          char *str, int duplicate);()</B
></TD
><TD
>Adds a string to the object.</TD
></TR
><TR
><TD
><B
CLASS="function"
>add_property_stringl(zval *object, char *key,
          char *str, uint length, int duplicate);()</B
></TD
><TD
>Adds a string of the specified length to the object. This
         function is faster than <A
HREF="zend-api.add-property-string.html"
><B
CLASS="function"
>add_property_string()</B
></A
> and also
         binary-safe.</TD
></TR
><TR
><TD
>&#13;         <B
CLASS="function"
>add_property_zval(zval *obect, char *key, zval *container):()</B
>
        </TD
><TD
>&#13;         Adds a <TT
CLASS="literal"
>zval</TT
> container to the object. This is useful if you
         have to add properties which aren't simple types like integers or strings but
         arrays or other objects.
        </TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.resource"
>Resources</A
></H2
><P
>&#13;		Resources are a special kind of data type in PHP. The term
		<SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>resources</I
></SPAN
> doesn't really refer to any special
		kind of data, but to an abstraction method for maintaining any kind
		of information. Resources are kept in a special resource list within
		Zend. Each entry in the list has a correspondending type definition
		that denotes the kind of resource to which it refers. Zend then
		internally manages all references to this resource. Access to a
		resource is never possible directly - only via a provided API. As soon
		as all references to a specific resource are lost, a corresponding
		shutdown function is called.
	</P
><P
>&#13;		For example, resources are used to store database links and file
		descriptors. The <SPAN
CLASS="emphasis"
><I
CLASS="emphasis"
>de facto</I
></SPAN
> standard implementation
		can be found in the MySQL module, but other modules such as the Oracle
		module also make use of resources.
		<DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>
      In fact, a resource can be a pointer to anything you need to
      handle in your functions (e.g. pointer to a structure) and the
      user only has to pass a single resource variable to your
      function.
     </P
></BLOCKQUOTE
></DIV
>
   </P
><P
>&#13;		To create a new resource you need to register a resource
		destruction handler for it. Since you can store any kind of data as a
		resource, Zend needs to know how to free this resource if its not longer
		needed. This works by registering your own resource destruction handler
		to Zend which in turn gets called by Zend whenever your resource can be
		freed (whether manually or automatically).  Registering your resource
		handler within Zend returns you the <SPAN
CLASS="strong"
><B
CLASS="emphasis"
>resource
		type handle</B
></SPAN
> for that resource.  This handle is needed
		whenever you want to access a resource of this type later and is most
		of time stored in a global static variable within your extension.
		There is no need to worry about thread safety here because you only
		register your resource handler once during module initialization.
   </P
><P
>&#13;		The Zend function to register your resource handler is defined as:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>ZEND_API int zend_register_list_destructors_ex(rsrc_dtor_func_t ld, rsrc_dtor_func_t pld, char *type_name, int module_number);</PRE
></TD
></TR
></TABLE
>
   </P
><P
>&#13;		There are two different kinds of resource destruction handlers you can
		pass to this function: a handler for normal resources and a handler
		for persistent resources. Persistent resources are for example used
		for database connection. When registering a resource, either of these
		handlers must be given. For the other handler just pass
		<TT
CLASS="literal"
>NULL</TT
>.
   </P
><P
>&#13;		<A
HREF="zend-api.zend-register-list-destructors-ex.html"
><B
CLASS="function"
>zend_register_list_destructors_ex()</B
></A
> accepts the
		following parameters:
		<DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN256100"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="5*"
TITLE="col2"><TBODY
><TR
><TD
><TT
CLASS="literal"
>ld</TT
></TD
><TD
>Normal resource destruction
         handler callback</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>pld</TT
></TD
><TD
>Pesistent resource destruction
         handler callback</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>type_name</TT
></TD
><TD
>A string specifying the name of
         your resource. It's always a good thing to
         specify a unique name within PHP for the resource type
         so when the user for example calls
         <TT
CLASS="literal"
>var_dump($resource);</TT
>
         he also gets the name of the resource.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>module_number</TT
></TD
><TD
>The <TT
CLASS="literal"
>module_number</TT
>
         is automatically available in your
         <TT
CLASS="literal"
>PHP_MINIT_FUNCTION</TT
>
         function and therefore you just pass it over.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
		The return value is a unique integer ID for your
		<SPAN
CLASS="strong"
><B
CLASS="emphasis"
>resource type</B
></SPAN
>.
   </P
><P
>&#13;		The resource destruction handler (either normal or persistent
		resources) has the following prototype:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>void resource_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC);</PRE
></TD
></TR
></TABLE
>
		The passed <TT
CLASS="literal"
>rsrc</TT
> is a pointer to the following structure:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>typedef struct _zend_rsrc_list_entry {
     
    void *ptr;
    int type;
    int refcount;

} zend_rsrc_list_entry;</PRE
></TD
></TR
></TABLE
>
		The member <TT
CLASS="literal"
>void *ptr</TT
> is the actual pointer to
		your resource.
   </P
><P
>&#13;		Now we know how to start things, we define our own resource we want
		register within Zend. It is only a simple structure with two integer
		members:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>typedef struct {
     
    int resource_link;
    int resource_type;

} my_resource;</PRE
></TD
></TR
></TABLE
>
		Our resource destruction handler is probably going to look something like this:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {

    // You most likely cast the void pointer to your structure type

    my_resource *my_rsrc = (my_resource *) rsrc-&#62;ptr;

    // Now do whatever needs to be done with you resource. Closing
    // Files, Sockets, freeing additional memory, etc.
    // Also, don't forget to actually free the memory for your resource too!

    do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
}</PRE
></TD
></TR
></TABLE
>
		<DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>One important thing to mention: If your resource
		is a rather complex structure which also contains pointers to
		memory you allocated during runtime you have to free them
		<SPAN
CLASS="strong"
><B
CLASS="emphasis"
>before</B
></SPAN
> freeing
		the resource itself!
     </P
></BLOCKQUOTE
></DIV
>
   </P
><P
>&#13;		Now that we have defined
		<P
></P
><OL
TYPE="1"
><LI
><P
>what our resource is and</P
></LI
><LI
><P
>our resource destruction handler</P
></LI
></OL
>
		we can go on and do the rest of the steps:
		<P
></P
><OL
TYPE="1"
><LI
><P
>create a global variable within the extension holding
       the resource ID so it can be accessed from every function
       which needs it</P
></LI
><LI
><P
>define the resource name</P
></LI
><LI
><P
>write the resource destruction handler</P
></LI
><LI
><P
>and finally register the handler</P
></LI
></OL
>
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>// Somewhere in your extension, define the variable for your registered resources.
    // If you wondered what 'le' stands for: it simply means 'list entry'.
    static int le_myresource;

    // It's nice to define your resource name somewhere
    #define le_myresource_name  "My type of resource"

    [...]

    // Now actually define our resource destruction handler
    void my_destruction_handler(zend_rsrc_list_entry *rsrc TSRMLS_DC) {

        my_resource *my_rsrc = (my_resource *) rsrc-&#62;ptr;
        do_whatever_needs_to_be_done_with_the_resource(my_rsrc);
    }

    [...]

    PHP_MINIT_FUNCTION(my_extension) {

        // Note that 'module_number' is already provided through the
        // PHP_MINIT_FUNCTION() function definition.

        le_myresource = zend_register_list_destructors_ex(my_destruction_handler, NULL, le_myresource_name, module_number);

        // You can register additional resources, initialize
        // your global vars, constants, whatever.
    }</PRE
></TD
></TR
></TABLE
>
   </P
><P
>&#13;		To actually register a new resource you use can either use
		the <A
HREF="zend-api.zend-register-resource.html"
><B
CLASS="function"
>zend_register_resource()</B
></A
> function or
		the <B
CLASS="function"
>ZEND_REGISTER_RESOURE()</B
> macro, both
		defined in zend_list.h . Although the arguments for both map
		1:1 it's a good idea to always use macros to be upwards
		compatible:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>int ZEND_REGISTER_RESOURCE(zval *rsrc_result, void *rsrc_pointer, int rsrc_type);</PRE
></TD
></TR
></TABLE
>
		<DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN256156"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="5*"
TITLE="col2"><TBODY
><TR
><TD
><TT
CLASS="literal"
>rsrc_result</TT
></TD
><TD
>This is an already initialized
         <TT
CLASS="literal"
>zval *</TT
> container.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>rsrc_pointer</TT
></TD
><TD
>Your resource pointer you want to
         store.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>rsrc_type</TT
></TD
><TD
>The type which you received when
         you registered the resource destruction handler. If you
         followed the naming scheme this would be
         <TT
CLASS="literal"
>le_myresource</TT
>.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
		The return value is a unique integer identifier for that resource.
   </P
><P
>&#13;		What is really going on when you register a new resource is it gets
		inserted in an internal list in Zend and the result is just stored
		in the given <TT
CLASS="literal"
>zval *</TT
> container:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>rsrc_id = zend_list_insert(rsrc_pointer, rsrc_type);
     
    if (rsrc_result) {
        rsrc_result-&#62;value.lval = rsrc_id;
        rsrc_result-&#62;type = IS_RESOURCE;
    }

    return rsrc_id;</PRE
></TD
></TR
></TABLE
>
    The returned <TT
CLASS="literal"
>rsrc_id</TT
> uniquely identifies the newly
    registered resource. You can use the macro
    <TT
CLASS="literal"
>RETURN_RESOURE</TT
> to return it to the user:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>RETURN_RESOURCE(rsrc_id)</PRE
></TD
></TR
></TABLE
>
    <DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>注意: </B
>It is common practice that if you want to return the resource
      immediately to the user you specify the <TT
CLASS="literal"
>return_value</TT
>
      as the <TT
CLASS="literal"
>zval *</TT
> container.
     </P
></BLOCKQUOTE
></DIV
>
   </P
><P
>&#13;		Zend now keeps track of all references to this resource. As soon as
		all references to the resource are lost, the destructor that you
		previously registered for this resource is called. The nice thing
		about this setup is that you don't have to worry about memory leakages
		introduced by allocations in your module - just register all memory
		allocations that your calling script will refer to as resources. As
		soon as the script decides it doesn't need them anymore, Zend will
		find out and tell you.
   </P
><P
>&#13;		Now that the user got his resource, at some point he is passing it
		back to one of your functions. The <CODE
CLASS="envar"
>value.lval</CODE
> inside
		the <TT
CLASS="literal"
>zval *</TT
> container contains the key to your
		resource and thus can be used to fetch the resource with the following
		macro:
		<TT
CLASS="literal"
>ZEND_FETCH_RESOURCE</TT
>:
		<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>ZEND_FETCH_RESOURCE(rsrc, rsrc_type, rsrc_id, default_rsrc_id, resource_type_name, resource_type)</PRE
></TD
></TR
></TABLE
>
		<DIV
CLASS="informaltable"
><P
></P
><A
NAME="AEN256191"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="5*"
TITLE="col2"><TBODY
><TR
><TD
><TT
CLASS="literal"
>rsrc</TT
></TD
><TD
>This is your pointer which will
         point to your previously registered resource.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>rsrc_type</TT
></TD
><TD
>This is the typecast argument for
         your pointer, e.g. <TT
CLASS="literal"
>myresource *</TT
>.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>rsrc_id</TT
></TD
><TD
>This is the address of the
         <TT
CLASS="literal"
>zval *</TT
>container the user passed to
         your function, e.g. <TT
CLASS="literal"
>&#38;z_resource</TT
> if
         <TT
CLASS="literal"
>zval *z_resource</TT
> is given.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>default_rsrc_id</TT
></TD
><TD
>This integer specifies the default
         resource <TT
CLASS="literal"
>ID</TT
> if no resource could be fetched
         or -1.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>resource_type_name</TT
></TD
><TD
>This is the name of the requested resource.
         It's a string and is used when the resource can't be
         found or is invalid to form a meaningful error
         message.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>resource_type</TT
></TD
><TD
>The <TT
CLASS="literal"
>resource_type</TT
>
         you got back when registering the resource destruction handler.
         In our example this was <CODE
CLASS="envar"
>le_myresource</CODE
>.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
		This macro has no return value.
		It is for the developers convenience and takes care
		of TSRMLS arguments passing and also does check if the resource
		could be fetched.
		It throws a warning message and returns the current PHP function
		with <TT
CLASS="literal"
>NULL</TT
> if there was a problem retrieving the
		resource.
   </P
><P
>&#13;		To force removal of a resource from the list, use the function
		<A
HREF="zend-api.zend-list-delete.html"
><B
CLASS="function"
>zend_list_delete()</B
></A
>. You can also force the
		reference count to increase if you know that you're creating another
		reference for a previously allocated value (for example, if you're
		automatically reusing a default database link). For this case, use the
		function <A
HREF="zend-api.zend-list-addref.html"
><B
CLASS="function"
>zend_list_addref()</B
></A
>. To search for
		previously allocated resource entries, use
		<A
HREF="zend-api.zend-list-find.html"
><B
CLASS="function"
>zend_list_find()</B
></A
>. The complete API can be found
		in <TT
CLASS="filename"
>zend_list.h</TT
>.
   </P
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.global"
>Macros for Automatic Global Variable Creation</A
></H2
><P
>&#13;    In addition to the macros discussed earlier, a few macros allow
    easy creation of simple global variables. These are nice to know
    in case you want to introduce global flags, for example. This is
    somewhat bad practice, but Table <A
HREF="zend.variables.html#tab.macros-global-vars"
>表 46-12</A
> 
    describes macros that do
    exactly this task. They don't need any <CODE
CLASS="envar"
>zval</CODE
>
    allocation; you simply have to supply a variable name and value.
   </P
><DIV
CLASS="table"
><A
NAME="tab.macros-global-vars"
></A
><P
><B
>表 46-12. Macros for Global Variable Creation</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1*"
TITLE="col1"><COL
WIDTH="1*"
TITLE="col2"><TBODY
><TR
><TD
>Macro</TD
><TD
>Description</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>SET_VAR_STRING(name, value)</TT
></TD
><TD
>Creates a new string.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>SET_VAR_STRINGL(name, value,
          length)</TT
></TD
><TD
>Creates a new string of the specified length. This macro
         is faster than <TT
CLASS="literal"
>SET_VAR_STRING</TT
> and also binary-safe.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>SET_VAR_LONG(name, value)</TT
></TD
><TD
>Creates a new long.</TD
></TR
><TR
><TD
><TT
CLASS="literal"
>SET_VAR_DOUBLE(name, value)</TT
></TD
><TD
>Creates a new double.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="sect2"
><H2
CLASS="sect2"
><A
NAME="zend.variables.constant"
>Creating Constants</A
></H2
><P
>&#13;    Zend supports the creation of true constants (as opposed to
    regular variables). Constants are accessed without the typical
    dollar sign (<TT
CLASS="literal"
>$</TT
>) prefix and are available in all
    scopes. Examples include <TT
CLASS="literal"
>TRUE</TT
> and
    <TT
CLASS="literal"
>FALSE</TT
>, to name just two.
   </P
><P
>&#13;    To create your own constants, you can use the macros in
    <A
HREF="zend.variables.html#tab.create-const"
>表 46-13</A
>. 
    All the macros create a constant with the specified name and value.
   </P
><P
>&#13;    You can also specify flags for each constant: 
    <P
></P
><UL
><LI
><P
>&#13;       <TT
CLASS="literal"
>CONST_CS</TT
> - This constant's name is to be
       treated as case sensitive.
      </P
></LI
><LI
><P
>&#13;       <TT
CLASS="literal"
>CONST_PERSISTENT</TT
> - This constant is
       persistent and won't be "forgotten" when the current process
       carrying this constant shuts down.
      </P
></LI
></UL
> To use the flags, combine them using a inary OR:
    <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>// register a new constant of type "long"
     REGISTER_LONG_CONSTANT("NEW_MEANINGFUL_CONSTANT", 324, CONST_CS |
     CONST_PERSISTENT);</PRE
></TD
></TR
></TABLE
> There are two types of
    macros -      	 	<TT
CLASS="literal"
>REGISTER_*_CONSTANT</TT
>
    and<TT
CLASS="literal"
>REGISTER_MAIN_*_CONSTANT</TT
>. The first type
    creates constants bound to the current module. These constants are
    dumped from the symbol table as soon as the module that registered
    the constant is unloaded from memory. The second type creates
    constants that remain in the symbol table independently of the
    module.
   </P
><DIV
CLASS="table"
><A
NAME="tab.create-const"
></A
><P
><B
>表 46-13. Macros for Creating Constants</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL
WIDTH="1.53*"
TITLE="col1"><COL
WIDTH="1*"
TITLE="col2"><TBODY
><TR
><TD
>Macro</TD
><TD
>Description</TD
></TR
><TR
><TD
> 
         <TT
CLASS="literal"
>REGISTER_LONG_CONSTANT(name, value, flags)</TT
>
         <TT
CLASS="literal"
>REGISTER_MAIN_LONG_CONSTANT(name, value, flags)</TT
>
        </TD
><TD
>Registers a new constant of type long.</TD
></TR
><TR
><TD
> 
         <TT
CLASS="literal"
>REGISTER_DOUBLE_CONSTANT(name, value, flags)</TT
>
         <TT
CLASS="literal"
>REGISTER_MAIN_DOUBLE_CONSTANT(name, value, flags)</TT
>
        </TD
><TD
>Registers a new constant of type double.</TD
></TR
><TR
><TD
> 
         <TT
CLASS="literal"
>REGISTER_STRING_CONSTANT(name, value, flags)</TT
>
         <TT
CLASS="literal"
>REGISTER_MAIN_STRING_CONSTANT(name, value, flags)</TT
>
        </TD
><TD
> Registers a new constant of type string. The specified
         string must reside in Zend's internal memory.</TD
></TR
><TR
><TD
> 
         <TT
CLASS="literal"
>REGISTER_STRINGL_CONSTANT(name, value, length, flags)</TT
> 
         <TT
CLASS="literal"
>REGISTER_MAIN_STRINGL_CONSTANT(name, value, length,
          flags)</TT
>
        </TD
><TD
>Registers a new constant of type string. The string length
         is explicitly set to <CODE
CLASS="envar"
>length</CODE
>. The specified string must reside
         in Zend's internal memory.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="zend.arguments.html"
ACCESSKEY="P"
>上一页</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>起始页</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="zend.copy-constructor.html"
ACCESSKEY="N"
>下一页</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Accepting Arguments</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="zend.html"
ACCESSKEY="U"
>上一级</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Duplicating Variable Contents: The Copy Constructor</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional