GtkSharp/doc/en/Gnome.Vfs/ModuleCallback.xml

<Type Name="ModuleCallback" FullName="Gnome.Vfs.ModuleCallback">
  <TypeSignature Language="C#" Value="public abstract class ModuleCallback" Maintainer="auto" />
  <AssemblyInfo>
    <AssemblyName>gnome-vfs-sharp</AssemblyName>
    <AssemblyPublicKey>[00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00 00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00 71 EB 6C 55 75 52 9C BF 72 44 F7 A6 EA 05 62 84 F9 EA E0 3B CF F2 CC 13 2C 9C 49 0A B3 09 EA B0 B5 6B CE 44 9D F5 03 D9 C0 A8 1E 52 05 85 CD BE 70 E2 FB 90 43 4B AC 04 FA 62 22 A8 00 98 B7 A1 A7 B3 AF 99 1A 41 23 24 BB 43 25 F6 B8 65 BB 64 EB F6 D1 C2 06 D5 73 2D DF BC 70 A7 38 9E E5 3E 0C 24 6E 32 79 74 1A D0 05 03 E4 98 42 E1 9B F3 7B 19 8B 40 21 26 CB 36 89 C2 EA 64 96 A4 7C B4]</AssemblyPublicKey>
    <AssemblyVersion>2.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
  <Docs>
    <summary>Abstract class used by modules for asking an application for necessary information (authentication for example).</summary>
    <remarks>
      <example>
        <code lang="C#">
using GLib;
using Gnome.Vfs;
using System;
using System.Text;

namespace Test.Gnome.Vfs {
	public class TestCallback {
		private static MainLoop loop;
	
		static void Main (string[] args)
		{
			if (args.Length != 1) {
				Console.WriteLine ("Usage: TestCallback &lt;uri&gt;");
				return;
			}
		
			Gnome.Vfs.Vfs.Initialize ();

			Gnome.Vfs.Uri uri = new Gnome.Vfs.Uri (args[0]);
			Handle handle;

			// Test 1: Attempt to access a URI requiring authentication w/o a callback registered.
			try {
				handle = Sync.Open (uri, OpenMode.Read);
				Sync.Close (handle);
				Console.WriteLine ("Uri '{0}' doesn't require authentication", uri);
				return;
			} catch (VfsException ex) {
				if (ex.Result != Result.ErrorAccessDenied)
					throw ex;
			}
			
			// Test 2: Attempt an open that requires authentication.
			ModuleCallbackFullAuthentication cb = new ModuleCallbackFullAuthentication ();
			cb.Callback += new ModuleCallbackHandler (OnAuthenticate);
			cb.SetDefault ();
			
			handle = Sync.Open (uri, OpenMode.Read);
			Sync.Close (handle);

			// Test 3: This call should not require any new authentication.
			Console.WriteLine ("File info: \n{0}", uri.GetFileInfo ());
			
			// Test 4: Attempt a call to the parent uri.
			FileInfo[] entries = Directory.GetEntries (uri.Parent);
			Console.WriteLine ("Directory '{0}' has {1} entries", uri.Parent, entries.Length);
			
			// Test 5: Pop the authentication callback and try again.
			cb.Pop ();
			try {
				handle = Sync.Open (uri, OpenMode.Read);
			} catch (VfsException ex) {
				if (ex.Result != Result.ErrorAccessDenied)
					throw ex;
			}
			
			Gnome.Vfs.Vfs.Shutdown ();
		}
		
		private static void OnAuthenticate (ModuleCallback cb)
		{
			ModuleCallbackFullAuthentication fcb = cb as ModuleCallbackFullAuthentication;
			Console.Write ("Enter your username ({0}): ", fcb.Username);
			string username = Console.ReadLine ();
			Console.Write ("Enter your password : ");
			string passwd = Console.ReadLine ();
			
			if (username.Length &gt; 0)
				fcb.Username = username;
			fcb.Password = passwd;
		}
	}
}
  </code>
      </example>
    </remarks>
  </Docs>
  <Base>
    <BaseTypeName>System.Object</BaseTypeName>
  </Base>
  <Interfaces />
  <Members>
    <Member MemberName="Push">
      <MemberSignature Language="C#" Value="public abstract void Push ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Set this ModuleCallback as a temporary handler. <see cref="M:Gnome.Vfs.ModuleCallback.Callback" /> will be called on the same thread as the gnome-vfs operation that invokes it. The temporary handler is set per-thread.</summary>
        <remarks>
          <para>
            <see cref="M:Gnome.Vfs.ModuleCallback.Pop" /> removes the most recently set temporary handler. The temporary handlers are treated as a first-in first-out stack.</para>
          <para>Use this function to set a temporary callback handler for a single call or a few calls. You can use <see cref="M:Gnome.Vfs.ModuleCallback.SetDefault" /> to set a callback function that will establish a permanent global setting for all threads instead.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="Pop">
      <MemberSignature Language="C#" Value="public abstract void Pop ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Remove the temporary handler set with <see cref="M:Gnome.Vfs.ModuleCallback.Push" />. If another temporary handler was previously set on the same thread, it becomes the current handler. Otherwise, the default handler, if any, becomes current.</summary>
        <remarks>The temporary handlers are treated as a first-in first-out stack.</remarks>
      </Docs>
    </Member>
    <Member MemberName="SetDefault">
      <MemberSignature Language="C#" Value="public abstract void SetDefault ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Set this <see cref="T:Gnome.Vfs.ModuleCallback" /> as the default handler. <see cref="M:Gnome.Vfs.ModuleCallback.Callback" /> will be called on the same thread as the gnome-vfs operation that invokes it. The default value is shared for all threads, but setting it is thread-safe.</summary>
        <remarks>Use this function if you want to set a handler to be used by your whole application. You can use <see cref="M:Gnome.Vfs.ModuleCallback.Push" /> to set a callback function that will temporarily override the default on the current thread instead. Or you can also use <see cref="M:Gnome.Vfs.ModuleCallback.SetDefaultAsync" /> to set an async callback function.</remarks>
      </Docs>
    </Member>
    <Member MemberName="PushAsync">
      <MemberSignature Language="C#" Value="public abstract void PushAsync ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Set <see cref="M:Gnome.Vfs.ModuleCallback.Callback" /> as a temprary async handler. <see cref="M:Gnome.Vfs.ModuleCallback.Callback" /> will be called from a callback on the main thread. It will be passed a response function which should be called to signal completion of the callback. The callback function itself may return in the meantime.</summary>
        <remarks>
          <para>The temporary async handler is set per-thread.</para>
          <para>
            <see cref="M:Gnome.Vfs.ModuleCallback.PopAsync" /> removes the most recently set temporary temporary handler. The temporary async handlers are treated as a first-in first-out stack.</para>
          <para>Use this function to set a temporary async callback handler for a single call or a few calls. You can use <see cref="M:Gnome.Vfs.ModuleCallback.SetDefaultAsync" /> to set an async callback function that will establish a permanent global setting for all threads instead.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="PopAsync">
      <MemberSignature Language="C#" Value="public abstract void PopAsync ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Remove the temporary async handler most recently set with <see cref="M:Gnome.Vfs.PushAsync" />. If another temporary async handler was previously set on the same thread, it becomes the current handler. Otherwise, the default async handler, if any, becomes current.</summary>
        <remarks>The temporary async handlers are treated as a first-in first-out stack.</remarks>
      </Docs>
    </Member>
    <Member MemberName="SetDefaultAsync">
      <MemberSignature Language="C#" Value="public abstract void SetDefaultAsync ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Set the default async callback. <see cref="M:Gnome.Vfs.ModuleCallback.Callback" /> will be called from a callback on the main thread. It will be passed a response function which should be called to signal completion of the callback. The callback function itself may return in the meantime.</summary>
        <remarks>
          <para>The default value is shared for all threads, but setting it is thread-safe.</para>
          <para>Use this function if you want to globally set a callback handler for use with async operations.</para>
          <para>You can use <see cref="M:Gnome.Vfs.ModuleCallback.PushAsync" /> to set an async callback function that will temporarily override the default on the current thread instead. Or you can also use <see cref="M:Gnome.Vfs.ModuleCallback.SetDefault" /> to set a regular callback function.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="protected ModuleCallback ();" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters />
      <Docs>
        <summary>To be added</summary>
        <remarks>To be added</remarks>
      </Docs>
    </Member>
    <Member MemberName="Callback">
      <MemberSignature Language="C#" Value="public abstract event Gnome.Vfs.ModuleCallbackHandler Callback;" />
      <MemberType>Event</MemberType>
      <ReturnValue>
        <ReturnType>Gnome.Vfs.ModuleCallbackHandler</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Event which is called when a gnome-vfs module requires additional information from an application such as authentication.</summary>
        <remarks>Implementations of <see cref="T:Gnome.Vfs.ModuleCallback" /> have properties such as <see cref="M:Gnome.Vfs.ModuleCallbackFullAuthentication.Username" /> which can be retrieved and set from the <see cref="M:Gnome.Vfs.ModuleCallback.Callback" /> handler. These properties are only valid during the callback activation.</remarks>
      </Docs>
    </Member>
  </Members>
</Type>