BlockLiteral.xml

<Type Name="BlockLiteral" FullName="ObjCRuntime.BlockLiteral">
  <TypeSignature Language="C#" Value="public struct BlockLiteral" />
  <TypeSignature Language="ILAsm" Value=".class public sequential ansi sealed beforefieldinit BlockLiteral extends System.ValueType" />
  <TypeSignature Language="DocId" Value="T:ObjCRuntime.BlockLiteral" />
  <TypeSignature Language="F#" Value="type BlockLiteral = struct" />
  <AssemblyInfo>
    <AssemblyName>Xamarin.iOS</AssemblyName>
    <AssemblyVersion>0.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <AssemblyInfo>
    <AssemblyName>Xamarin.Mac</AssemblyName>
    <AssemblyVersion>0.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <Base>
    <BaseTypeName>System.ValueType</BaseTypeName>
  </Base>
  <Interfaces />
  <Docs>
    <summary>Wraps a ECMA CLI delegate (C# lambdas, anonymous methods or delegates) as an Objective-C block.</summary>
    <remarks>
      <para>
	This is a low-level class that is automatically used by the Xamarin.iOS bindings when using Objective-C block APIs.
      </para>
      <para>
	In the C#/ECMA CLI world delegates are automatically turned into blocks that can be consumed by Objective-C blocks-aware APIs.
      </para>
      <para>
	If you need to P/Invoke a native C method that takes a block
	parameter, you would need to manually setup the BlockLiteral
	object and declare a proxy method that is invoked by the block
	handler and will invoke your managed code.

      </para>
      <example>
        <code lang="csharp lang-csharp"><![CDATA[
// Imagine that you want to invoke the following method:
// void SetupHandler (void (^block)(double offset, int count));

// Declare the signature of the method that users would have to provide
public delegate void SetupHandlerCallback (double offset, int count);
// Declare the signature of the method that the block will call
delegate void SetupHandlerCallbackProxy (IntPtr blockLiteral, double offset, int count);
// Static variable that points to our trampoline method
static readonly SetupHandlerCallback static_handler = TrampolineHandler;

// Our trampoline method must be registered for reverse-callback with Mono
// it takes one extra parameter than the signature, which is the pointer
// to the block that was originally passed.
[MonoPInvokeCallback (typeof (SetupHandlerCallbackProxy))]
static void TrampolineHandler (IntPtr block, double offset, int count)
{
    // Find the delegate for the block and call it
    var callback = BlockLiteral.GetTarget<SetupHandlerCallback> (block);
    if (callback != null)
        callback (offset, count);
}

[DllImport ("YourLibrary")]
static extern void SetupHandler (ref BlockLiteral block);

public void SetupHandler (SetupHandlerCallback callback)
{
    if (callback == null)
        throw new ArgumentNullException (nameof (callback));
    BlockLiteral block = new BlockLiteral ();
    block.SetupBlock (static_handler, callback);
    try {
        SetupHandler (ref block);
    } finally {
        block.CleanupBlock ();
    }
}
]]></code>
      </example>
    </remarks>
  </Docs>
  <Members>
    <Member MemberName="CleanupBlock">
      <MemberSignature Language="C#" Value="public void CleanupBlock ();" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance void CleanupBlock() cil managed" />
      <MemberSignature Language="DocId" Value="M:ObjCRuntime.BlockLiteral.CleanupBlock" />
      <MemberSignature Language="F#" Value="member this.CleanupBlock : unit -&gt; unit" Usage="blockLiteral.CleanupBlock " />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
        <AssemblyName>Xamarin.iOS</AssemblyName>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Releases the resources associated with this block.</summary>
        <remarks>
          <para>This releases the GCHandle that points to the user delegate.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="GetDelegateForBlock&lt;T&gt;">
      <MemberSignature Language="C#" Value="public T GetDelegateForBlock&lt;T&gt; () where T : class;" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance !!T GetDelegateForBlock&lt;class T&gt;() cil managed" />
      <MemberSignature Language="DocId" Value="M:ObjCRuntime.BlockLiteral.GetDelegateForBlock``1" />
      <MemberSignature Language="F#" Value="member this.GetDelegateForBlock : unit -&gt; 'T (requires 'T : null)" Usage="blockLiteral.GetDelegateForBlock " />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
        <AssemblyName>Xamarin.iOS</AssemblyName>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>T</ReturnType>
      </ReturnValue>
      <TypeParameters>
        <TypeParameter Name="T">
          <Constraints>
            <ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
          </Constraints>
        </TypeParameter>
      </TypeParameters>
      <Parameters />
      <Docs>
        <typeparam name="T">Desired type to get, the delegate must be compatible with this type.</typeparam>
        <summary>This method supports the Xamarin.iOS runtime and is not intended for use by application developers.</summary>
        <returns>Returns a delegate of the given type that can be used to invoke the Objective-C block in the provided handle.</returns>
        <remarks>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="GetTarget&lt;T&gt;">
      <MemberSignature Language="C#" Value="public static T GetTarget&lt;T&gt; (IntPtr block) where T : class;" />
      <MemberSignature Language="ILAsm" Value=".method public static hidebysig !!T GetTarget&lt;class T&gt;(native int block) cil managed" />
      <MemberSignature Language="DocId" Value="M:ObjCRuntime.BlockLiteral.GetTarget``1(System.IntPtr)" />
      <MemberSignature Language="F#" Value="static member GetTarget : nativeint -&gt; 'T (requires 'T : null)" Usage="ObjCRuntime.BlockLiteral.GetTarget block" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyName>Xamarin.iOS</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>T</ReturnType>
      </ReturnValue>
      <TypeParameters>
        <TypeParameter Name="T">
          <Constraints>
            <ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
          </Constraints>
        </TypeParameter>
      </TypeParameters>
      <Parameters>
        <Parameter Name="block" Type="System.IntPtr" />
      </Parameters>
      <Docs>
        <typeparam name="T">The type of the managed delegate to return.</typeparam>
        <param name="block">The pointer to the native block.</param>
        <summary>If this block represents a managed delegate, this method will return that managed delegate.</summary>
        <returns>The managed delegate for this block.</returns>
        <remarks>
          <para>Behavior is undefined if this block does not represent a managed delegate.</para>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="IsManagedBlock">
      <MemberSignature Language="C#" Value="public static bool IsManagedBlock (IntPtr block);" />
      <MemberSignature Language="ILAsm" Value=".method public static hidebysig bool IsManagedBlock(native int block) cil managed" />
      <MemberSignature Language="DocId" Value="M:ObjCRuntime.BlockLiteral.IsManagedBlock(System.IntPtr)" />
      <MemberSignature Language="F#" Value="static member IsManagedBlock : nativeint -&gt; bool" Usage="ObjCRuntime.BlockLiteral.IsManagedBlock block" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
        <AssemblyName>Xamarin.iOS</AssemblyName>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <Attributes>
        <Attribute>
          <AttributeName>System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)</AttributeName>
        </Attribute>
      </Attributes>
      <ReturnValue>
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="block" Type="System.IntPtr" />
      </Parameters>
      <Docs>
        <param name="block">The pointer to the native block.</param>
        <summary>This method determines whether a block is wrapping a managed delegate or if it's an Objective-C block.</summary>
        <returns>Returns true if the specified block contains a managed delegate.</returns>
        <remarks>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="SetupBlock">
      <MemberSignature Language="C#" Value="public void SetupBlock (Delegate trampoline, Delegate userDelegate);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance void SetupBlock(class System.Delegate trampoline, class System.Delegate userDelegate) cil managed" />
      <MemberSignature Language="DocId" Value="M:ObjCRuntime.BlockLiteral.SetupBlock(System.Delegate,System.Delegate)" />
      <MemberSignature Language="F#" Value="member this.SetupBlock : Delegate * Delegate -&gt; unit" Usage="blockLiteral.SetupBlock (trampoline, userDelegate)" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
        <AssemblyName>Xamarin.iOS</AssemblyName>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="trampoline" Type="System.Delegate" />
        <Parameter Name="userDelegate" Type="System.Delegate" />
      </Parameters>
      <Docs>
        <param name="trampoline">The trampoline must be a static delegate. Xamarin.iOS will automatically keep a reference to this delegate.</param>
        <param name="userDelegate">The user code to invoke.</param>
        <summary>Sets up a block using a trampoline and a user delegate.</summary>
        <remarks>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="SetupBlockUnsafe">
      <MemberSignature Language="C#" Value="public void SetupBlockUnsafe (Delegate trampoline, Delegate userDelegate);" />
      <MemberSignature Language="ILAsm" Value=".method public hidebysig instance void SetupBlockUnsafe(class System.Delegate trampoline, class System.Delegate userDelegate) cil managed" />
      <MemberSignature Language="DocId" Value="M:ObjCRuntime.BlockLiteral.SetupBlockUnsafe(System.Delegate,System.Delegate)" />
      <MemberSignature Language="F#" Value="member this.SetupBlockUnsafe : Delegate * Delegate -&gt; unit" Usage="blockLiteral.SetupBlockUnsafe (trampoline, userDelegate)" />
      <MemberType>Method</MemberType>
      <AssemblyInfo>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
        <AssemblyName>Xamarin.iOS</AssemblyName>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <Attributes>
        <Attribute>
          <AttributeName>System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)</AttributeName>
        </Attribute>
      </Attributes>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="trampoline" Type="System.Delegate" />
        <Parameter Name="userDelegate" Type="System.Delegate" />
      </Parameters>
      <Docs>
        <param name="trampoline">The trampoline must be a static delegate. The developer's code must keep a reference to it.</param>
        <param name="userDelegate">The user code to invoke.</param>
        <summary>Sets up a block using a trampoline and a user delegate.</summary>
        <remarks>
        </remarks>
      </Docs>
    </Member>
    <Member MemberName="Target">
      <MemberSignature Language="C#" Value="public object Target { get; }" />
      <MemberSignature Language="ILAsm" Value=".property instance object Target" />
      <MemberSignature Language="DocId" Value="P:ObjCRuntime.BlockLiteral.Target" />
      <MemberSignature Language="F#" Value="member this.Target : obj" Usage="ObjCRuntime.BlockLiteral.Target" />
      <MemberType>Property</MemberType>
      <AssemblyInfo>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
        <AssemblyName>Xamarin.iOS</AssemblyName>
      </AssemblyInfo>
      <AssemblyInfo>
        <AssemblyName>Xamarin.Mac</AssemblyName>
        <AssemblyVersion>0.0.0.0</AssemblyVersion>
      </AssemblyInfo>
      <ReturnValue>
        <ReturnType>System.Object</ReturnType>
      </ReturnValue>
      <Docs>
        <summary>Returns the target object for the block.</summary>
        <value>
        </value>
        <remarks>
        </remarks>
      </Docs>
    </Member>
  </Members>
</Type>