<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="SoupCutClient">
<refmeta>
<refentrytitle role="top_of_page" id="SoupCutClient.top_of_page">Convenience HTTP client API</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CUTTER Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Convenience HTTP client API</refname>
<refpurpose>API to work as HTTP client.</refpurpose>
</refnamediv>

<refsynopsisdiv id="SoupCutClient.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>struct              <link linkend="SoupCutClient-struct">SoupCutClient</link>;
struct              <link linkend="SoupCutClientClass">SoupCutClientClass</link>;
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="soupcut-client-get">soupcut_client_get</link>                  (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *uri</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *first_query_name</parameter>,
                                                         <parameter>...</parameter>);
<link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link> *      <link linkend="soupcut-client-get-async-context">soupcut_client_get_async_context</link>    (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>);
<link linkend="SoupMessage"><returnvalue>SoupMessage</returnvalue></link> *       <link linkend="soupcut-client-get-latest-message">soupcut_client_get_latest_message</link>   (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>);
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="soupcut-client-get-n-messages">soupcut_client_get_n_messages</link>       (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>);
<link linkend="SoupCutClient"><returnvalue>SoupCutClient</returnvalue></link> *     <link linkend="soupcut-client-new">soupcut_client_new</link>                  (<parameter><type>void</type></parameter>);
<link linkend="guint"><returnvalue>guint</returnvalue></link>               <link linkend="soupcut-client-send-message">soupcut_client_send_message</link>         (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>,
                                                         <parameter><link linkend="SoupMessage"><type>SoupMessage</type></link> *message</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="soupcut-client-set-base">soupcut_client_set_base</link>             (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *uri</parameter>);
</synopsis>
</refsynopsisdiv>
<refsect1 id="SoupCutClient.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----SoupCutClient
</synopsis>
</refsect1>
<refsect1 id="SoupCutClient.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="SoupCutClient--async">async</link>&quot;                    <link linkend="gboolean"><type>gboolean</type></link>              : Read / Write
</synopsis>
</refsect1>

<refsect1 id="SoupCutClient.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="SoupCutClient"><type>SoupCutClient</type></link> works as a HTTP client. It accepts
multiple requests and responses are managed by
<link linkend="SoupCutClient"><type>SoupCutClient</type></link>. <link linkend="SoupCutClient"><type>SoupCutClient</type></link> related assertions are
also provided.
</para>
</refsect1>
<refsect1 id="SoupCutClient.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="SoupCutClient-struct" role="struct">
<title>struct SoupCutClient</title>
<indexterm zone="SoupCutClient-struct"><primary>SoupCutClient</primary></indexterm>
<programlisting>struct SoupCutClient;</programlisting>
<para>
</para></refsect2>
<refsect2 id="SoupCutClientClass" role="struct">
<title>struct SoupCutClientClass</title>
<indexterm zone="SoupCutClientClass"><primary>SoupCutClientClass</primary></indexterm>
<programlisting>struct SoupCutClientClass {
    GObjectClass parent_class;
};
</programlisting>
<para>
</para></refsect2>
<refsect2 id="soupcut-client-get" role="function" condition="since:1.0.8">
<title>soupcut_client_get ()</title>
<indexterm zone="soupcut-client-get" role="1.0.8"><primary>soupcut_client_get</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               soupcut_client_get                  (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *uri</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *first_query_name</parameter>,
                                                         <parameter>...</parameter>);</programlisting>
<para>
Send a GET request to <parameter>uri</parameter> with queries. If the base URI of <parameter>client</parameter>
is set by <link linkend="soupcut-client-set-base"><function>soupcut_client_set_base()</function></link>, the destination URI is composed of the base URI and <parameter>uri</parameter>. If not, <parameter>uri</parameter> must be a fully qualified URI.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&#160;:</term>
<listitem><simpara>an URI string.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_query_name</parameter>&#160;:</term>
<listitem><simpara>the name of the first query parameter.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>pairs of query parameter names and values, starting with <parameter>first_query_name</parameter>, terminated by <link linkend="NULL:CAPS"><literal>NULL</literal></link></simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a status code of the response.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>
<refsect2 id="soupcut-client-get-async-context" role="function" condition="since:1.0.8">
<title>soupcut_client_get_async_context ()</title>
<indexterm zone="soupcut-client-get-async-context" role="1.0.8"><primary>soupcut_client_get_async_context</primary></indexterm>
<programlisting><link linkend="GMainContext"><returnvalue>GMainContext</returnvalue></link> *      soupcut_client_get_async_context    (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>);</programlisting>
<para>
Returns the asynch_context of <parameter>client</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a <link linkend="GMainContext"><type>GMainContext</type></link> of <parameter>client</parameter>, which may be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>
<refsect2 id="soupcut-client-get-latest-message" role="function" condition="since:1.0.8">
<title>soupcut_client_get_latest_message ()</title>
<indexterm zone="soupcut-client-get-latest-message" role="1.0.8"><primary>soupcut_client_get_latest_message</primary></indexterm>
<programlisting><link linkend="SoupMessage"><returnvalue>SoupMessage</returnvalue></link> *       soupcut_client_get_latest_message   (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>);</programlisting>
<para>
Returns the latest <link linkend="SoupMessage"><type>SoupMessage</type></link> <parameter>client</parameter> sent.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the latest <link linkend="SoupMessage"><type>SoupMessage</type></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>
<refsect2 id="soupcut-client-get-n-messages" role="function" condition="since:1.0.8">
<title>soupcut_client_get_n_messages ()</title>
<indexterm zone="soupcut-client-get-n-messages" role="1.0.8"><primary>soupcut_client_get_n_messages</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               soupcut_client_get_n_messages       (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>);</programlisting>
<para>
Returns the number of messages <parameter>client</parameter> sent.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the number of messages.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>
<refsect2 id="soupcut-client-new" role="function" condition="since:1.0.8">
<title>soupcut_client_new ()</title>
<indexterm zone="soupcut-client-new" role="1.0.8"><primary>soupcut_client_new</primary></indexterm>
<programlisting><link linkend="SoupCutClient"><returnvalue>SoupCutClient</returnvalue></link> *     soupcut_client_new                  (<parameter><type>void</type></parameter>);</programlisting>
<para>
Creates and returns a new <link linkend="SoupCutClient"><type>SoupCutClient</type></link>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a new <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>
<refsect2 id="soupcut-client-send-message" role="function" condition="since:1.0.8">
<title>soupcut_client_send_message ()</title>
<indexterm zone="soupcut-client-send-message" role="1.0.8"><primary>soupcut_client_send_message</primary></indexterm>
<programlisting><link linkend="guint"><returnvalue>guint</returnvalue></link>               soupcut_client_send_message         (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>,
                                                         <parameter><link linkend="SoupMessage"><type>SoupMessage</type></link> *message</parameter>);</programlisting>
<para>
Send <parameter>message</parameter> with <parameter>client</parameter>. <parameter>client</parameter> remebers all the messages it sent.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>message</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupMessage"><type>SoupMessage</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a status code of the response.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>
<refsect2 id="soupcut-client-set-base" role="function" condition="since:1.0.8">
<title>soupcut_client_set_base ()</title>
<indexterm zone="soupcut-client-set-base" role="1.0.8"><primary>soupcut_client_set_base</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                soupcut_client_set_base             (<parameter><link linkend="SoupCutClient"><type>SoupCutClient</type></link> *client</parameter>,
                                                         <parameter>const <link linkend="gchar"><type>gchar</type></link> *uri</parameter>);</programlisting>
<para>
Set <parameter>uri</parameter> as a base uri of <parameter>client</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>client</parameter>&#160;:</term>
<listitem><simpara>a <link linkend="SoupCutClient"><type>SoupCutClient</type></link>.</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&#160;:</term>
<listitem><simpara>a base uri.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.0.8</para></refsect2>

</refsect1>
<refsect1 id="SoupCutClient.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="SoupCutClient--async" role="property"><title>The <literal>&quot;async&quot;</literal> property</title>
<indexterm zone="SoupCutClient--async"><primary>SoupCutClient:async</primary></indexterm>
<programlisting>  &quot;async&quot;                    <link linkend="gboolean"><type>gboolean</type></link>              : Read / Write</programlisting>
<para>True if the session is asynchronous.</para><para>Default value: FALSE</para>
</refsect2>
</refsect1>
<refsect1 id="SoupCutClient.see-also">
<title>See Also</title>
<link
           linkend="cutter-Assertions-for-HTTP-client-and-server">
           Assertions for HTTP client and server</link>
</refsect1>

</refentry>
