<?xml version="1.0"?>
<!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="GSocketService">
<refmeta>
<refentrytitle role="top_of_page" id="GSocketService.top_of_page">GSocketService</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GIO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GSocketService</refname>
<refpurpose>Make it easy to implement a network service</refpurpose>
</refnamediv>

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

<synopsis>
                    <link linkend="GSocketService-struct">GSocketService</link>;
<link linkend="GSocketService">GSocketService</link> *    <link linkend="g-socket-service-new">g_socket_service_new</link>                (void);
<link linkend="void">void</link>                <link linkend="g-socket-service-start">g_socket_service_start</link>              (<link linkend="GSocketService">GSocketService</link> *service);
<link linkend="void">void</link>                <link linkend="g-socket-service-stop">g_socket_service_stop</link>               (<link linkend="GSocketService">GSocketService</link> *service);
<link linkend="gboolean">gboolean</link>            <link linkend="g-socket-service-is-active">g_socket_service_is_active</link>          (<link linkend="GSocketService">GSocketService</link> *service);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GSocketService.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----<link linkend="GSocketListener">GSocketListener</link>
         +----GSocketService
               +----<link linkend="GThreadedSocketService">GThreadedSocketService</link>
</synopsis>
</refsect1>






<refsect1 id="GSocketService.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
  &quot;<link linkend="GSocketService-incoming">incoming</link>&quot;                                       : Run Last
</synopsis>
</refsect1>


<refsect1 id="GSocketService.description" role="desc">
<title role="desc.title">Description</title>
<para>
A <link linkend="GSocketService"><type>GSocketService</type></link> is an object that represents a service that is
provided to the network or over local sockets.  When a new
connection is made to the service the <link linkend="GSocketService--incoming"><type>"incoming"</type></link>
signal is emitted.
</para>
<para>
A <link linkend="GSocketService"><type>GSocketService</type></link> is a subclass of <link linkend="GSocketListener"><type>GSocketListener</type></link> and you need
to add the addresses you want to accept connections on to the
with the <link linkend="GSocketListener"><type>GSocketListener</type></link> APIs.
</para>
<para>
There are two options for implementing a network service based on
<link linkend="GSocketService"><type>GSocketService</type></link>. The first is to create the service using
<link linkend="g-socket-service-new"><function>g_socket_service_new()</function></link> and to connect to the <link linkend="GSocketService--incoming"><type>"incoming"</type></link>
signal. The second is to subclass <link linkend="GSocketService"><type>GSocketService</type></link> and override the
default signal handler implementation.
</para>
<para>
In either case, the handler must immediately return, or else it
will block additional incoming connections from being serviced.
If you are interested in writing connection handlers that contain
blocking code then see <link linkend="GThreadedSocketService"><type>GThreadedSocketService</type></link>.
</para>
<para>
The socket service runs on the main loop in the main thread, and is
not threadsafe in general. However, the calls to start and stop
the service are threadsafe so these can be used from threads that
handle incoming clients.</para>
<para>
</para>
</refsect1>

<refsect1 id="GSocketService.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GSocketService-struct" role="struct">
<title>GSocketService</title>
<indexterm zone="GSocketService-struct" role="2.22"><primary sortas="SocketService">GSocketService</primary></indexterm><programlisting>typedef struct _GSocketService GSocketService;</programlisting>
<para>
A helper class for handling accepting incomming connections in the
glib mainloop.</para>
<para>
</para><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-socket-service-new" role="function" condition="since:2.22">
<title>g_socket_service_new ()</title>
<indexterm zone="g-socket-service-new" role="2.22"><primary sortas="socket_service_new">g_socket_service_new</primary></indexterm><programlisting><link linkend="GSocketService">GSocketService</link> *    g_socket_service_new                (void);</programlisting>
<para>
Creates a new <link linkend="GSocketService"><type>GSocketService</type></link> with no sockets to listen for.
New listeners can be added with e.g. <link linkend="g-socket-listener-add-address"><function>g_socket_listener_add_address()</function></link>
or <link linkend="g-socket-listener-add-inet-port"><function>g_socket_listener_add_inet_port()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GSocketService"><type>GSocketService</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-socket-service-start" role="function" condition="since:2.22">
<title>g_socket_service_start ()</title>
<indexterm zone="g-socket-service-start" role="2.22"><primary sortas="socket_service_start">g_socket_service_start</primary></indexterm><programlisting><link linkend="void">void</link>                g_socket_service_start              (<link linkend="GSocketService">GSocketService</link> *service);</programlisting>
<para>
Starts the service, i.e. start accepting connections
from the added sockets when the mainloop runs.
</para>
<para>
This call is threadsafe, so it may be called from a thread
handling an incomming client request.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSocketService"><type>GSocketService</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-socket-service-stop" role="function" condition="since:2.22">
<title>g_socket_service_stop ()</title>
<indexterm zone="g-socket-service-stop" role="2.22"><primary sortas="socket_service_stop">g_socket_service_stop</primary></indexterm><programlisting><link linkend="void">void</link>                g_socket_service_stop               (<link linkend="GSocketService">GSocketService</link> *service);</programlisting>
<para>
Stops the service, i.e. stops accepting connections
from the added sockets when the mainloop runs.
</para>
<para>
This call is threadsafe, so it may be called from a thread
handling an incomming client request.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSocketService"><type>GSocketService</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-socket-service-is-active" role="function" condition="since:2.22">
<title>g_socket_service_is_active ()</title>
<indexterm zone="g-socket-service-is-active" role="2.22"><primary sortas="socket_service_is_active">g_socket_service_is_active</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_socket_service_is_active          (<link linkend="GSocketService">GSocketService</link> *service);</programlisting>
<para>
Check whether the service is active or not. An active
service will accept new clients that connect, while
a non-active service will let connecting clients queue
up until the service is started.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSocketService"><type>GSocketService</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the service is active, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>

</refsect1>

<refsect1 id="GSocketService.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GSocketService-incoming" role="signal"><title>The <literal>&quot;incoming&quot;</literal> signal</title>
<indexterm zone="GSocketService-incoming" role="2.22"><primary sortas="SocketService::incoming">GSocketService::incoming</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            user_function                      (<link linkend="GSocketService">GSocketService</link>    *service,
                                                        <link linkend="GSocketConnection">GSocketConnection</link> *connection,
                                                        <link linkend="GObject">GObject</link>           *source_object,
                                                        <link linkend="gpointer">gpointer</link>           user_data)          : Run Last</programlisting>
<para>
The ::incoming signal is emitted when a new incoming connection
to <parameter>service</parameter> needs to be handled. The handler must initiate the
handling of <parameter>connection</parameter>, but may not block; in essence,
asynchronous operations must be used.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GSocketService"><type>GSocketService</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>connection</parameter>&#160;:</term>
<listitem><simpara> a new <link linkend="GSocketConnection"><type>GSocketConnection</type></link> object.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>source_object</parameter>&#160;:</term>
<listitem><simpara> the source_object passed to <link linkend="g-socket-listener-add-address"><function>g_socket_listener_add_address()</function></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>returns</parameter>&#160;:</term>
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>connection</parameter> has been handled.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to stop other handlers from being called
</simpara></listitem></varlistentry>
</variablelist><para>Since 2.22</para></refsect2>
</refsect1>


<refsect1 id="GSocketService.see-also">
<title>See Also</title>
#GThreadedSocketService, <link linkend="GSocketListener"><type>GSocketListener</type></link>.
</refsect1>

</refentry>
