Blame docs/reference/gdata-running.xml

Packit 4b6dd7
Packit 4b6dd7
Packit 4b6dd7
<refentry id="gdata-running">
Packit 4b6dd7
	<refmeta>
Packit 4b6dd7
		<refentrytitle role="top_of_page" id="gdata-overview.top_of_page">Running GData Applications</refentrytitle>
Packit 4b6dd7
		<manvolnum>3</manvolnum>
Packit 4b6dd7
		<refmiscinfo>GDATA Library</refmiscinfo>
Packit 4b6dd7
	</refmeta>
Packit 4b6dd7
	<refnamediv>
Packit 4b6dd7
		<refname>Running GData Applications</refname>
Packit 4b6dd7
		<refpurpose>running and debugging GData applications</refpurpose>
Packit 4b6dd7
	</refnamediv>
Packit 4b6dd7
Packit 4b6dd7
	<refsect1>
Packit 4b6dd7
		<title>Running and Debugging GData Applications</title>
Packit 4b6dd7
Packit 4b6dd7
		<refsect2>
Packit 4b6dd7
			<title>Environment variables</title>
Packit 4b6dd7
			<para>libgdata makes use of a few environment variables which affect how it runs, mainly with respect to debugging.</para>
Packit 4b6dd7
Packit 4b6dd7
			<formalpara id="LIBGDATA_DEBUG">
Packit 4b6dd7
				<title><envar>LIBGDATA_DEBUG</envar></title>
Packit 4b6dd7
				<para>If this environment variable is set to one of the following values, libgdata will give debug output
Packit 4b6dd7
					(at various levels). If it's unset, no debug output will be produced.
Packit 4b6dd7
					<variablelist>
Packit 4b6dd7
						<varlistentry>
Packit 4b6dd7
							<term>0</term>
Packit 4b6dd7
							<listitem><para>Output no debug messages or network logs.</para></listitem>
Packit 4b6dd7
						</varlistentry>
Packit 4b6dd7
						<varlistentry>
Packit 4b6dd7
							<term>1</term>
Packit 4b6dd7
							<listitem><para>Output debug messages, but not network logs.</para></listitem>
Packit 4b6dd7
						</varlistentry>
Packit 4b6dd7
						<varlistentry>
Packit 4b6dd7
							<term>2</term>
Packit 4b6dd7
							<listitem><para>Output debug messages and network traffic headers.</para></listitem>
Packit 4b6dd7
						</varlistentry>
Packit 4b6dd7
						<varlistentry>
Packit 4b6dd7
							<term>3</term>
Packit 4b6dd7
							<listitem><para>Output debug messages and full network traffic logs.</para></listitem>
Packit 4b6dd7
						</varlistentry>
Packit 4b6dd7
					</variablelist>
Packit 4b6dd7
				</para>
Packit 4b6dd7
				<para>So, to debug a program which uses libgdata, run it from a terminal with the following command:</para>
Packit 4b6dd7
				<screen><prompt>$</prompt><userinput>LIBGDATA_DEBUG=3 ./my-program-name &> libgdata.log</userinput></screen>
Packit 4b6dd7
			</formalpara>
Packit 4b6dd7
		</refsect2>
Packit 4b6dd7
Packit 4b6dd7
		<refsect2>
Packit 4b6dd7
			<title>Debugging Advice</title>
Packit 4b6dd7
			<para>The easiest way to debug problems with libgdata is to use the
Packit 4b6dd7
			      <link linkend="LIBGDATA_DEBUG"><envar>LIBGDATA_DEBUG</envar></link> environment variable to observe all the network
Packit 4b6dd7
			      traffic being transmitted and received by libgdata. Typically, any problems will occur in the final network
Packit 4b6dd7
			      request/response, which is the last one in the log output.</para>
Packit 4b6dd7
			<para>If debugging using the environment variables and log output is not possible, it is sometimes possible to diagnose problems
Packit 4b6dd7
			      by examining the error responses sent by the Google servers to libgdata. These are exposed as the error messages returned
Packit 4b6dd7
			      by libgdata methods; so when handling errors from libgdata method calls, it is a good idea to output the message from
Packit 4b6dd7
			      the <link linkend="GError"><type>GError</type></link> to a debug log, or even as a warning in the user's
Packit 4b6dd7
			      <filename>.xsession-errors</filename> file.</para>
Packit 4b6dd7
			<example>
Packit 4b6dd7
				<title>Error Handling when Uploading a Document</title>
Packit 4b6dd7
				<programlisting>
Packit 4b6dd7
				GDataUploadStream *upload_stream;
Packit 4b6dd7
				GError *error = NULL; /* make sure to initialise the GError to NULL */
Packit 4b6dd7
Packit 4b6dd7
				/* Other code goes here. */
Packit 4b6dd7
Packit 4b6dd7
				upload_stream = gdata_documents_service_upload_document (service, document, slug, content_type, destination_folder, NULL,
Packit 4b6dd7
				                                                         &error);
Packit 4b6dd7
Packit 4b6dd7
				/* Handle any errors. */
Packit 4b6dd7
				if (error != NULL) {
Packit 4b6dd7
					/* Note that the error message is outputted to the terminal/logs.
Packit 4b6dd7
					 * It will contain important debugging information from the Google servers. */
Packit 4b6dd7
					g_error ("Error getting upload stream: %s", error->message);
Packit 4b6dd7
					g_error_free (error);
Packit 4b6dd7
Packit 4b6dd7
					return;
Packit 4b6dd7
				}
Packit 4b6dd7
				</programlisting>
Packit 4b6dd7
			</example>
Packit 4b6dd7
		</refsect2>
Packit 4b6dd7
	</refsect1>
Packit 4b6dd7
</refentry>