fdw_helper_doc.patch

commit 5a2f1314d197c037dfd55ea1dc0395f46333c05d
Author: Shigeru Hanada <shigeru.hanada@gmail.com>
Date:   Fri Oct 21 11:54:39 2011 +0900

    Add document about helper functions for FDW authors.

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 76ff243..db02d13 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -235,4 +235,98 @@ EndForeignScan (ForeignScanState *node);
 
    </sect1>
 
+   <sect1 id="fdw-helpers">
+    <title>Foreign Data Wrapper Helper Functions</title>
+
+    <para>
+     Several helper functions are exported from core so that authors of FDW
+     can get easy access to attributes of FDW-related objects such as FDW
+     options.
+    </para>
+
+    <para>
+<programlisting>
+ForeignDataWrapper *
+GetForeignDataWrapper(Oid fdwid);
+</programlisting>
+
+     This function returns a <structname>ForeignDataWrapper</structname> object
+     for a foreign-data wrapper with given oid.  A
+     <structname>ForeignDataWrapper</structname> object contains oid of the
+     wrapper itself, oid of the owner of the wrapper, name of the wrapper, oid
+     of fdwhandler function, oid of fdwvalidator function, and FDW options in
+     the form of list of <structname>DefElem</structname>.
+    </para>
+
+    <para>
+<programlisting>
+ForeignServer *
+GetForeignServer(Oid serverid);
+</programlisting>
+
+     This function returns a <structname>ForeignServer</structname> object for
+     a foreign server with given oid.  A <structname>ForeignServer</structname>
+     object contains oid of the server, oid of the wrapper for the server, oid
+     of the owner of the server, name of the server, type of the server,
+     version of the server, and FDW options in the form of list of
+     <structname>DefElem</structname>.
+    </para>
+
+    <para>
+<programlisting>
+UserMapping *
+GetUserMapping(Oid userid, Oid serverid);
+</programlisting>
+
+     This function returns a <structname>UserMapping</structname> object for a
+     user mapping with given oid pair.  A <structname>UserMapping</structname>
+     object contains oid of the user, oid of the server, and FDW options in the
+     form of list of <structname>DefElem</structname>.
+    </para>
+
+    <para>
+<programlisting>
+ForeignTable *
+GetForeignTable(Oid relid);
+</programlisting>
+
+     This function returns a <structname>ForeignTable</structname> object for a
+     foreign table with given oid.  A <structname>ForeignTable</structname>
+     object contains oid of the foreign table, oid of the server for the table,
+     and FDW options in the form of list of <structname>DefElem</structname>.
+    </para>
+
+    <para>
+     Some object types have name-based functions.
+    </para>
+
+    <para>
+<programlisting>
+ForeignDataWrapper *
+GetForeignDataWrapperByName(const char *name, bool missing_ok);
+</programlisting>
+
+     This function returns a <structname>ForeignDataWrapper</structname> object
+     for a foreign-data wrapper with given name.  If the wrapper is not found,
+     return NULL if missing_ok was true, otherwise raise an error.
+    </para>
+
+    <para>
+<programlisting>
+ForeignServer *
+GetForeignServerByName(const char *name, bool missing_ok);
+</programlisting>
+
+     This function returns a <structname>ForeignServer</structname> object for
+     a foreign server with given name.  If the server is not found, return NULL
+     if missing_ok was true, otherwise raise an error.
+    </para>
+
+    <para>
+     To use any of these functions, you need to include
+     <filename>foreign/foreign.h</filename> in your source file.
+    </para>
+
+  </sect1>
+
  </chapter>