libpq.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

<synopsis>
PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</synopsis>
</para>
<para>
   These two functions are used to open a connection to a database server such
   that your application's thread of execution is not blocked on remote I/O
   whilst doing so.
   The point of this approach is that the waits for I/O to complete can occur
   in the application's main loop, rather than down inside
   <function>PQconnectdb</>, and so the application can manage this
   operation in parallel with other activities.
  </para>
  <para>
   The database connection is made using the parameters taken from the string
   <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
   the same format as described above for <function>PQconnectdb</function>.
  </para>
  <para>
   Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, so long as a number of
   restrictions are met:
   <itemizedlist>
    <listitem>
     <para>
      The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
      name and reverse name queries are not made. See the documentation of
      these parameters under <function>PQconnectdb</function> above for details.
     </para>
    </listitem>

    <listitem>
     <para>
      If you call <function>PQtrace</function>, ensure that the stream object
      into which you trace will not block.
     </para>
    </listitem>

    <listitem>
     <para>
      You ensure that the socket is in the appropriate state
      before calling <function>PQconnectPoll</function>, as described below.
     </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   To begin a nonblocking connection request, call <literal>conn = PQconnectStart("<replaceable>connection_info_string</>")</literal>.
   If <varname>conn</varname> is null, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
   structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
   representing a valid connection to the database). On return from
   <function>PQconnectStart</function>, call <literal>status = PQstatus(conn)</literal>. If <varname>status</varname> equals
   <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
  </para>
  <para>
   If <function>PQconnectStart</> succeeds, the next stage is to poll
   <application>libpq</> so that it may proceed with the connection sequence.
   Use <function>PQsocket(conn)</function> to obtain the descriptor of the
   socket underlying the database connection.
   Loop thus: If <function>PQconnectPoll(conn)</function> last returned
   <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
   read (as indicated by <function>select()</>, <function>poll()</>, or
   similar system function).
   Then call <function>PQconnectPoll(conn)</function> again.
   Conversely, if <function>PQconnectPoll(conn)</function> last returned
   <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
   to write, then call <function>PQconnectPoll(conn)</function> again.
   If you have yet to call
   <function>PQconnectPoll</function>, i.e., just after the call to
   <function>PQconnectStart</function>, behave as if it last returned
   <symbol>PGRES_POLLING_WRITING</symbol>.  Continue this loop until
   <function>PQconnectPoll(conn)</function> returns
   <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure
   has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating the connection
   has been successfully made.
  </para>

  <para>
    At any time during connection, the status of the connection may be
    checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
    connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
    connection is ready.  Both of these states are equally detectable
    from the return value of <function>PQconnectPoll</>, described above. Other states may also occur
    during (and only during) an asynchronous connection procedure. These
    indicate the current stage of the connection procedure and may be useful
    to provide feedback to the user for example. These statuses are:

    <variablelist>
     <varlistentry>
      <term><symbol>CONNECTION_STARTED</symbol></term>
      <listitem>
       <para>
        Waiting for connection to be made.
       </para>
      </listitem>
     </varlistentry> 

     <varlistentry>
      <term><symbol>CONNECTION_MADE</symbol></term>
      <listitem>
       <para>
        Connection OK; waiting to send.
       </para>
      </listitem>
     </varlistentry>  

     <varlistentry>
      <term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
      <listitem>
       <para>
        Waiting for a response from the server.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><symbol>CONNECTION_AUTH_OK</symbol></term>
      <listitem>
       <para>
        Received authentication; waiting for backend start-up to finish.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><symbol>CONNECTION_SSL_STARTUP</symbol></term>
      <listitem>
       <para>
        Negotiating SSL encryption.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><symbol>CONNECTION_SETENV</symbol></term>
      <listitem>
       <para>
        Negotiating environment-driven parameter settings.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

    Note that, although these constants will remain (in order to maintain
    compatibility), an application should never rely upon these occurring in a
    particular order, or at all, or on the status always being one of these
    documented values. An application might do something like this:
<programlisting>
switch(PQstatus(conn))
{
    case CONNECTION_STARTED:
        feedback = "Connecting...";
        break;

    case CONNECTION_MADE:
        feedback = "Connected to server...";
        break;
.
.
.
    default:
        feedback = "Connecting...";
}
</programlisting>
  </para>

  <para>
   The <literal>connect_timeout</literal> connection parameter is ignored
   when using <function>PQconnectPoll</function>; it is the application's
   responsibility to decide whether an excessive amount of time has elapsed.
   Otherwise, <function>PQconnectStart</function> followed by a
   <function>PQconnectPoll</function> loop is equivalent to
   <function>PQconnectdb</function>.
  </para>

  <para>
   Note that if <function>PQconnectStart</function> returns a non-null pointer, you must call
   <function>PQfinish</function> when you are finished with it, in order to dispose of
   the structure and any associated memory blocks. This must be done even if
   the connection attempt fails or is abandoned.
  </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQconndefaults</function><indexterm><primary>PQconndefaults</></></term>
  <listitem>
   <para>
   Returns the default connection options.
<synopsis>
PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Character to display for this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
} PQconninfoOption;
</synopsis>
</para>

<para>
   Returns a connection options array.  This may be used to determine
   all possible <function>PQconnectdb</function> options and their
   current default values.  The return value points to an array of
   <structname>PQconninfoOption</structname> structures, which ends
   with an entry having a null <structfield>keyword</> pointer.  The
   null pointer is returned if memory could not be allocated. Note that
   the current default values (<structfield>val</structfield> fields)
   will depend on environment variables and other context.  Callers
   must treat the connection options data as read-only.
   </para>

   <para>
    After processing the options array, free it by passing it to
    <function>PQconninfoFree</function>.  If this is not done, a small amount of memory
    is leaked for each call to <function>PQconndefaults</function>.
   </para>

  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
  <listitem>
   <para>
   Closes  the  connection to the server.  Also frees
   memory used by the <structname>PGconn</structname> object.
<synopsis>
void PQfinish(PGconn *conn);
</synopsis>
</para>

<para>
   Note that even if the server connection attempt fails (as
   indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
   to free the memory used by the <structname>PGconn</structname> object.
   The <structname>PGconn</> pointer must not be used again after
   <function>PQfinish</function> has been called.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQreset</function><indexterm><primary>PQreset</></></term>
  <listitem>
   <para>
   Resets the communication channel to the server.
<synopsis>
void PQreset(PGconn *conn);
</synopsis>
</para>

<para>
   This function will close the connection
   to the server and attempt to  reestablish  a  new
   connection to the same server, using all the same
   parameters previously used.  This may be useful for
   error recovery if a working connection is lost.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term><function>PQresetStart</function><indexterm><primary>PQresetStart</></></term>
  <term><function>PQresetPoll</function><indexterm><primary>PQresetPoll</></></term>
  <listitem>
   <para>
   Reset the communication channel to the server, in a nonblocking manner.
<synopsis>
int PQresetStart(PGconn *conn);
</synopsis>
<synopsis>
PostgresPollingStatusType PQresetPoll(PGconn *conn);
</synopsis>
</para>

<para>
    These functions will close the connection to the server and attempt to
    reestablish a new connection to the same server, using all the same
    parameters previously used. This may be useful for error recovery if a
    working connection is lost. They differ from <function>PQreset</function> (above) in that they
    act in a nonblocking manner. These functions suffer from the same
    restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
   </para>
   <para>
    To initiate a connection reset, call <function>PQresetStart</function>. If it returns 0, the reset has failed. If it returns 1,
    poll the reset using <function>PQresetPoll</function> in exactly the same way as you would
    create the connection using <function>PQconnectPoll</function>.
   </para>
  </listitem>
 </varlistentry>

 </variablelist>
</para>
</sect1>

<sect1 id="libpq-status">
<title>Connection Status Functions</title>

  <para>
   These functions may be used to interrogate the status
   of an existing database connection object.
  </para>

<tip>
<para>
<indexterm><primary>libpq-fe.h</></>
<indexterm><primary>libpq-int.h</></>
<application>libpq</application> application programmers should be careful to
maintain the <structname>PGconn</structname> abstraction.  Use the accessor
functions described below to get
at the contents of <structname>PGconn</structname>.  Avoid directly referencing the fields of the
<structname>PGconn</> structure because they are subject to change in the future.
(Beginning in <productname>PostgreSQL</productname> release 6.4, the
definition of the <type>struct</type> behind <structname>PGconn</> is not even provided in <filename>libpq-fe.h</filename>.
If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
soon.)
</para>
</tip>

<para>
The following functions return parameter values established at connection.
These values are fixed for the life of the <structname>PGconn</> object.

<variablelist>
<varlistentry>
<term><function>PQdb</function><indexterm><primary>PQdb</></></term>
<listitem>
<para>
         Returns the database name of the connection.
<synopsis>
char *PQdb(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQuser</function><indexterm><primary>PQuser</></></term>
<listitem>
<para>
         Returns the user name of the connection.
<synopsis>
char *PQuser(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><function>PQpass</function><indexterm><primary>PQpass</></></term>
<listitem>
<para>
         Returns the password of the connection.
<synopsis>
char *PQpass(const PGconn *conn);
</synopsis>
</para>
</listitem>
</varlistentry>