sdks/wasm/bindings.cs

   1 using System;
   2 using System.Text;
   3 using System.Collections.Generic;
   4 using System.Threading;
   5 using System.Threading.Tasks;
   6 using System.Reflection;
   7 using System.Runtime.InteropServices;
   8 using System.Runtime.CompilerServices;
   9
  10 /*
  11  * TODO:
  12  * - Expose annotated C# type to JS
  13  * - Add property fetch to JSObject
  14  * - Add typed method invoke support (get a delegate?)
  15  * - Add JS helpers to fetch wrapped methods, like to Module.cwrap
  16  * - Better Wrap C# exception when passing them as object (IE, on task failure)
  17  * - Make JSObject disposable (same for js objects)
  18 */
  19
  20 namespace WebAssembly
  21 {
  22     /// <summary>
  23     ///   Provides access to the Mono/WebAssembly runtime to perform tasks like invoking JavaScript functions and retrieving global variables.
  24     /// </summary>
  25     public sealed class Runtime
  26     {
  27         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  28         static extern string InvokeJS(string str, out int exceptional_result);
  29
  30         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  31         internal static extern object InvokeJSWithArgs(int js_obj_handle, string method, object[] _params, out int exceptional_result);
  32         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  33         internal static extern object GetObjectProperty(int js_obj_handle, string propertyName, out int exceptional_result);
  34         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  35         internal static extern object SetObjectProperty(int js_obj_handle, string propertyName, object value, bool createIfNotExists, bool hasOwnProperty, out int exceptional_result);
  36         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  37         internal static extern object GetGlobalObject(string globalName, out int exceptional_result);
  38
  39         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  40         internal static extern object ReleaseHandle(int js_obj_handle, out int exceptional_result);
  41         [MethodImplAttribute(MethodImplOptions.InternalCall)]
  42         internal static extern object ReleaseObject(object obj, out int exceptional_result);
  43
  44         /// <summary>
  45         ///   Execute the provided string in the JavaScript context
  46         public static string InvokeJS(string str)
  47         {
  48             int exception;
  49             var res = InvokeJS(str, out exception);
  50             if (exception != 0)
  51                 throw new JSException(res);
  52             return res;
  53         }
  54
  55         static Dictionary<int, JSObject> bound_objects = new Dictionary<int, JSObject>();
  56         static Dictionary<object, JSObject> raw_to_js = new Dictionary<object, JSObject>();
  57
  58         static int BindJSObject(int js_id)
  59         {
  60             JSObject obj;
  61             if (bound_objects.ContainsKey(js_id))
  62                 obj = bound_objects[js_id];
  63             else
  64                 bound_objects[js_id] = obj = new JSObject(js_id);
  65
  66             return (int)(IntPtr)obj.Handle;
  67         }
  68
  69         static int UnBindJSObject(int js_id)
  70         {
  71             if (bound_objects.ContainsKey(js_id))
  72             {
  73                 var obj = bound_objects[js_id];
  74                 bound_objects.Remove(js_id);
  75                 return (int)(IntPtr)obj.Handle;
  76             }
  77
  78             return 0;
  79
  80         }
  81
  82         static int BindJSObject(JSObject obj)
  83         {
  84
  85             int js_id = obj.JSHandle;
  86             if (js_id <= 0)
  87                 throw new JSException($"Invalid JS Object Handle {js_id}");
  88
  89             if (bound_objects.ContainsKey(js_id))
  90                 obj = bound_objects[js_id];
  91             else
  92                 bound_objects[js_id] = obj;
  93
  94             return (int)(IntPtr)obj.Handle;
  95         }
  96
  97         static int UnBindJSObjectAndFree(int js_id)
  98         {
  99             if (bound_objects.ContainsKey(js_id))
 100             {
 101                 var obj = bound_objects[js_id];
 102                 bound_objects.Remove(js_id);
 103                 var gCHandle = obj.Handle;
 104                 obj.Handle.Free();
 105                 obj.JSHandle = -1;
 106                 obj.RawObject = null;
 107                 return (int)(IntPtr)gCHandle;
 108             }
 109             return 0;
 110
 111         }
 112
 113
 114         static int UnBindRawJSObjectAndFree(int gcHandle)
 115         {
 116
 117             GCHandle h = (GCHandle)(IntPtr)gcHandle;
 118             JSObject obj = (JSObject)h.Target;
 119             if (obj != null && obj.RawObject != null)
 120             {
 121                 var raw_obj = obj.RawObject;
 122                 if (raw_to_js.ContainsKey(raw_obj))
 123                 {
 124                     raw_to_js.Remove(raw_obj);
 125                 }
 126
 127                 obj.Dispose();
 128
 129                 var gCHandle = obj.Handle;
 130                 obj.Handle.Free();
 131                 obj.JSHandle = -1;
 132                 return (int)(IntPtr)gCHandle;
 133             }
 134             return 0;
 135
 136         }
 137
 138         public static void FreeObject (object obj)
 139         {
 140             int exception;
 141             Runtime.ReleaseObject(obj, out exception);
 142             if (exception != 0)
 143                 throw new JSException($"Error releasing object on (raw-obj)");
 144
 145         }
 146
 147         static object CreateTaskSource(int js_id)
 148         {
 149             return new TaskCompletionSource<object>();
 150         }
 151
 152         static void SetTaskSourceResult(TaskCompletionSource<object> tcs, object result)
 153         {
 154             tcs.SetResult(result);
 155         }
 156
 157         static void SetTaskSourceFailure(TaskCompletionSource<object> tcs, string reason)
 158         {
 159             tcs.SetException(new JSException(reason));
 160         }
 161
 162         static int GetTaskAndBind(TaskCompletionSource<object> tcs, int js_id)
 163         {
 164             return BindExistingObject(tcs.Task, js_id);
 165         }
 166
 167         static int BindExistingObject(object raw_obj, int js_id)
 168         {
 169
 170             JSObject obj;
 171             if (raw_obj is JSObject)
 172                 obj = (JSObject)raw_obj;
 173             else if (raw_to_js.ContainsKey(raw_obj))
 174                 obj = raw_to_js[raw_obj];
 175             else
 176                 raw_to_js[raw_obj] = obj = new JSObject(js_id, raw_obj);
 177
 178             return (int)(IntPtr)obj.Handle;
 179         }
 180
 181         static int GetJSObjectId(object raw_obj)
 182         {
 183             JSObject obj = null;
 184             if (raw_obj is JSObject)
 185                 obj = (JSObject)raw_obj;
 186             else if (raw_to_js.ContainsKey(raw_obj))
 187                 obj = raw_to_js[raw_obj];
 188
 189             var js_handle = obj != null ? obj.JSHandle : -1;
 190
 191             return js_handle;
 192         }
 193
 194         static object GetMonoObject(int gc_handle)
 195         {
 196             GCHandle h = (GCHandle)(IntPtr)gc_handle;
 197             JSObject o = (JSObject)h.Target;
 198             if (o != null && o.RawObject != null)
 199                 return o.RawObject;
 200             return o;
 201         }
 202
 203         static object BoxInt(int i)
 204         {
 205             return i;
 206         }
 207         static object BoxDouble(double d)
 208         {
 209             return d;
 210         }
 211
 212         static object BoxBool(int b)
 213         {
 214             return b == 0 ? false : true;
 215         }
 216
 217         [StructLayout(LayoutKind.Explicit)]
 218         internal struct IntPtrAndHandle
 219         {
 220             [FieldOffset(0)]
 221             internal IntPtr ptr;
 222
 223             [FieldOffset(0)]
 224             internal RuntimeMethodHandle handle;
 225         }
 226
 227         //FIXME this probably won't handle generics
 228         static string GetCallSignature(IntPtr method_handle)
 229         {
 230             IntPtrAndHandle tmp = default(IntPtrAndHandle);
 231             tmp.ptr = method_handle;
 232
 233             var mb = MethodBase.GetMethodFromHandle(tmp.handle);
 234
 235             string res = "";
 236             foreach (var p in mb.GetParameters())
 237             {
 238                 var t = p.ParameterType;
 239
 240                 switch (Type.GetTypeCode(t))
 241                 {
 242                     case TypeCode.Byte:
 243                     case TypeCode.SByte:
 244                     case TypeCode.Int16:
 245                     case TypeCode.UInt16:
 246                     case TypeCode.Int32:
 247                     case TypeCode.UInt32:
 248                     case TypeCode.Boolean:
 249                         // Enums types have the same code as their underlying numeric types
 250                         if (t.IsEnum)
 251                             res += "j";
 252                         else
 253                             res += "i";
 254                         break;
 255                     case TypeCode.Int64:
 256                     case TypeCode.UInt64:
 257                         // Enums types have the same code as their underlying numeric types
 258                         if (t.IsEnum)
 259                             res += "k";
 260                         else
 261                             res += "l";
 262                         break;
 263                     case TypeCode.Single:
 264                         res += "f";
 265                         break;
 266                     case TypeCode.Double:
 267                         res += "d";
 268                         break;
 269                     case TypeCode.String:
 270                         res += "s";
 271                         break;
 272                     default:
 273                         if (t.IsValueType)
 274                             throw new Exception("Can't handle VT arguments");
 275                         res += "o";
 276                         break;
 277                 }
 278             }
 279             return res;
 280         }
 281
 282         static object ObjectToEnum(IntPtr method_handle, int parm, object obj)
 283         {
 284             IntPtrAndHandle tmp = default(IntPtrAndHandle);
 285             tmp.ptr = method_handle;
 286
 287             var mb = MethodBase.GetMethodFromHandle(tmp.handle);
 288             var parmType = mb.GetParameters()[parm].ParameterType;
 289             if (parmType.IsEnum)
 290                 return Runtime.EnumFromExportContract(parmType, obj);
 291             else
 292                 return null;
 293
 294         }
 295
 296
 297         static MethodInfo gsjsc;
 298         static void GenericSetupJSContinuation<T>(Task<T> task, JSObject cont_obj)
 299         {
 300             task.GetAwaiter().OnCompleted(() =>
 301             {
 302
 303                 if (task.Exception != null)
 304                     cont_obj.Invoke("reject", task.Exception.ToString());
 305                 else
 306                 {
 307                     cont_obj.Invoke("resolve", task.Result);
 308                 }
 309
 310                 cont_obj.Dispose();
 311                 FreeObject(task);
 312
 313             });
 314         }
 315
 316         static void SetupJSContinuation(Task task, JSObject cont_obj)
 317         {
 318             if (task.GetType() == typeof(Task))
 319             {
 320                 task.GetAwaiter().OnCompleted(() =>
 321                 {
 322
 323                     if (task.Exception != null)
 324                         cont_obj.Invoke("reject", task.Exception.ToString());
 325                     else
 326                         cont_obj.Invoke("resolve", null);
 327
 328                     cont_obj.Dispose();
 329                     FreeObject(task);
 330                 });
 331             }
 332             else
 333             {
 334                 //FIXME this is horrible codegen, we can do better with per-method glue
 335                 if (gsjsc == null)
 336                     gsjsc = typeof(Runtime).GetMethod("GenericSetupJSContinuation", BindingFlags.NonPublic | BindingFlags.Static);
 337                 gsjsc.MakeGenericMethod(task.GetType().GetGenericArguments()).Invoke(null, new object[] { task, cont_obj });
 338             }
 339         }
 340
 341
 342         /// <summary>
 343         ///   Fetches a global object from the Javascript world, either from the current brower window or from the node.js global context.
 344         /// </summary>
 345         /// <remarks>
 346         ///   This method returns the value of a global object marshalled for consumption in C#.
 347         /// </remarks>
 348         /// <returns>
 349         ///   <para>
 350         ///     The return value can either be a primitive (string, int, double), a <see
 351         ///     cref="T:WebAssembly.JSObject"/> for JavaScript objects, a <see
 352         ///     cref="T:System.Threading.Tasks.Task">(object) for JavaScript promises, an array of
 353         ///     a byte, int or double (for Javascript objects typed as ArrayBuffer) or a <see
 354         ///     cref="T:System.Func"/> to represent JavaScript functions.  The specific version of
 355         ///     the Func that will be returned depends on the parameters of the Javascript function
 356         ///     and return value.
 357         ///   </para>
 358         ///   <para>
 359         ///     The value of a returned promise (The Task(object) return) can in turn be any of the above
 360         ///     valuews.
 361         ///   </para>
 362         /// </returns>
 363         /// <param name="str">The name of the global object, or null if you want to retrieve the 'global' object itself.
 364         /// On a browser, this is the 'window' object, on node.js it is the 'global' object.
 365         /// </param>
 366         public static object GetGlobalObject(string str = null)
 367         {
 368             int exception;
 369             var globalHandle = Runtime.GetGlobalObject(str, out exception);
 370
 371             if (exception != 0)
 372                 throw new JSException($"Error obtaining a handle to global {str}");
 373
 374             return globalHandle;
 375         }
 376
 377         static string ObjectToString(object o)
 378         {
 379
 380             if (o is Enum)
 381                 return EnumToExportContract((Enum)o).ToString();
 382
 383             return o.ToString();
 384         }
 385         // This is simple right now and will include FlagsAttribute later.
 386         public static Enum EnumFromExportContract(Type enumType, object value)
 387         {
 388
 389             if (!enumType.IsEnum)
 390             {
 391                 throw new ArgumentException("Type provided must be an Enum.", nameof(enumType));
 392             }
 393
 394             if (value is string)
 395             {
 396
 397                 var fields = enumType.GetFields();
 398                 foreach (var fi in fields)
 399                 {
 400                     // Do not process special names
 401                     if (fi.IsSpecialName)
 402                         continue;
 403
 404                     ExportAttribute[] attributes =
 405                         (ExportAttribute[])fi.GetCustomAttributes(typeof(ExportAttribute), false);
 406
 407                     var enumConversionType = ConvertEnum.Default;
 408
 409                     object contractName = null;
 410
 411                     if (attributes != null && attributes.Length > 0)
 412                     {
 413                         enumConversionType = attributes[0].EnumValue;
 414                         if (enumConversionType != ConvertEnum.Numeric)
 415                             contractName = attributes[0].ContractName;
 416
 417                     }
 418
 419                     if (contractName == null)
 420                         contractName = fi.Name;
 421
 422                     switch (enumConversionType)
 423                     {
 424                         case ConvertEnum.ToLower:
 425                             contractName = contractName.ToString().ToLower();
 426                             break;
 427                         case ConvertEnum.ToUpper:
 428                             contractName = contractName.ToString().ToUpper();
 429                             break;
 430                         case ConvertEnum.Numeric:
 431                             contractName = (int)Enum.Parse(value.GetType(), contractName.ToString());
 432                             break;
 433                         default:
 434                             contractName = contractName.ToString();
 435                             break;
 436                     }
 437
 438                     if (contractName.ToString() == value.ToString())
 439                     {
 440                         return (Enum)Enum.Parse(enumType, fi.Name);
 441                     }
 442
 443                 }
 444
 445                 throw new ArgumentException($"Value is a name, but not one of the named constants defined for the enum of type: {enumType}.", nameof(value));
 446             }
 447             else
 448             {
 449                 return (Enum)Enum.ToObject(enumType, value);
 450             }
 451
 452             return null;
 453         }
 454
 455         // This is simple right now and will include FlagsAttribute later.
 456         public static object EnumToExportContract(Enum value)
 457         {
 458
 459             FieldInfo fi = value.GetType().GetField(value.ToString());
 460
 461             ExportAttribute[] attributes =
 462                 (ExportAttribute[])fi.GetCustomAttributes(typeof(ExportAttribute), false);
 463
 464             var enumConversionType = ConvertEnum.Default;
 465
 466             object contractName = null;
 467
 468             if (attributes != null && attributes.Length > 0)
 469             {
 470                 enumConversionType = attributes[0].EnumValue;
 471                 if (enumConversionType != ConvertEnum.Numeric)
 472                     contractName = attributes[0].ContractName;
 473
 474             }
 475
 476             if (contractName == null)
 477                 contractName = value;
 478
 479             switch (enumConversionType)
 480             {
 481                 case ConvertEnum.ToLower:
 482                     contractName = contractName.ToString().ToLower();
 483                     break;
 484                 case ConvertEnum.ToUpper:
 485                     contractName = contractName.ToString().ToUpper();
 486                     break;
 487                 case ConvertEnum.Numeric:
 488                     contractName = (int)Enum.Parse(value.GetType(), contractName.ToString());
 489                     break;
 490                 default:
 491                     contractName = contractName.ToString();
 492                     break;
 493             }
 494
 495             return contractName;
 496         }
 497
 498     }
 499
 500     public class JSException : Exception
 501     {
 502         public JSException(string msg) : base(msg) { }
 503     }
 504
 505     /// <summary>
 506     ///   JSObjects are wrappers for a native JavaScript object, and
 507     ///   they retain a reference to the JavaScript object for the lifetime of this C# object.
 508     /// </summary>
 509     public class JSObject : IDisposable
 510     {
 511         public int JSHandle { get; internal set; }
 512         internal GCHandle Handle;
 513         internal object RawObject;
 514
 515         internal JSObject(int js_handle)
 516         {
 517             this.JSHandle = js_handle;
 518             this.Handle = GCHandle.Alloc(this);
 519         }
 520
 521         internal JSObject(int js_id, object raw_obj)
 522         {
 523             this.JSHandle = js_id;
 524             this.Handle = GCHandle.Alloc(this);
 525             this.RawObject = raw_obj;
 526         }
 527
 528
 529         /// <returns>
 530         ///   <para>
 531         ///     The return value can either be a primitive (string, int, double), a <see
 532         ///     cref="T:WebAssembly.JSObject"/> for JavaScript objects, a <see
 533         ///     cref="T:System.Threading.Tasks.Task">(object) for JavaScript promises, an array of
 534         ///     a byte, int or double (for Javascript objects typed as ArrayBuffer) or a <see
 535         ///     cref="T:System.Func"/> to represent JavaScript functions.  The specific version of
 536         ///     the Func that will be returned depends on the parameters of the Javascript function
 537         ///     and return value.
 538         ///   </para>
 539         ///   <para>
 540         ///     The value of a returned promise (The Task(object) return) can in turn be any of the above
 541         ///     valuews.
 542         ///   </para>
 543         /// </returns>
 544         public object Invoke(string method, params object[] args)
 545         {
 546             int exception;
 547             var res = Runtime.InvokeJSWithArgs(JSHandle, method, args, out exception);
 548             if (exception != 0)
 549                 throw new JSException((string)res);
 550             return res;
 551         }
 552
 553         /// <summary>
 554         ///   Returns the named property from the object, or throws a JSException on error.
 555         /// </summary>
 556         /// <param name="name">The name of the property to lookup</param>
 557         /// <remarks>
 558         ///   This method can raise a <see cref="T:WebAssembly.JSException"/> if fetching the property in Javascript raises an exception.
 559         /// </remarks>
 560         /// <returns>
 561         ///   <para>
 562         ///     The return value can either be a primitive (string, int, double), a <see
 563         ///     cref="T:WebAssembly.JSObject"/> for JavaScript objects, a <see
 564         ///     cref="T:System.Threading.Tasks.Task">(object) for JavaScript promises, an array of
 565         ///     a byte, int or double (for Javascript objects typed as ArrayBuffer) or a <see
 566         ///     cref="T:System.Func"/> to represent JavaScript functions.  The specific version of
 567         ///     the Func that will be returned depends on the parameters of the Javascript function
 568         ///     and return value.
 569         ///   </para>
 570         ///   <para>
 571         ///     The value of a returned promise (The Task(object) return) can in turn be any of the above
 572         ///     valuews.
 573         ///   </para>
 574         /// </returns>
 575         public object GetObjectProperty(string expr)
 576         {
 577
 578             int exception;
 579             var propertyValue = Runtime.GetObjectProperty(JSHandle, expr, out exception);
 580
 581             if (exception != 0)
 582                 throw new JSException((string)propertyValue);
 583
 584             return propertyValue;
 585
 586         }
 587
 588         /// <summary>
 589         ///   Sets the named property to the provided value.
 590         /// </summary>
 591         /// <remarks>
 592         /// </remarks>
 593         /// <param name="name">The name of the property to lookup</param>
 594         /// <param name="value">The value can be a primitive type (int, double, string, bool), an
 595         /// array that will be surfaced as a typed ArrayBuffer (byte[], sbyte[], short[], ushort[],
 596         /// float[], double[]) </param>
 597         /// <param name="createIfNotExists">Defaults to <see langword="true"/> and creates the property on the javascript object if not found, if set to <see langword="false"/> it will not create the property if it does not exist.  If the property exists, the value is updated with the provided value.</param>
 598         /// <param name="hasOwnProperty"></param>
 599         public void SetObjectProperty(string expr, object value, bool createIfNotExists = true, bool hasOwnProperty = false)
 600         {
 601
 602             int exception;
 603             var setPropResult = Runtime.SetObjectProperty(JSHandle, expr, value, createIfNotExists, hasOwnProperty, out exception);
 604             if (exception != 0)
 605                 throw new JSException($"Error setting {expr} on (js-obj js '{JSHandle}' mono '{(IntPtr)Handle} raw '{RawObject != null})");
 606
 607         }
 608
 609         protected void FreeHandle()
 610         {
 611
 612             int exception;
 613             Runtime.ReleaseHandle(JSHandle, out exception);
 614             if (exception != 0)
 615                 throw new JSException($"Error releasing handle on (js-obj js '{JSHandle}' mono '{(IntPtr)Handle} raw '{RawObject != null})");
 616         }
 617
 618         public override bool Equals(System.Object obj)
 619         {
 620             if (obj == null || GetType() != obj.GetType())
 621             {
 622                 return false;
 623             }
 624             return JSHandle == (obj as JSObject).JSHandle;
 625         }
 626
 627         public override int GetHashCode()
 628         {
 629             return JSHandle;
 630         }
 631
 632         public void Dispose()
 633         {
 634             // Dispose of unmanaged resources.
 635             Dispose(true);
 636             // Suppress finalization.
 637             GC.SuppressFinalize(this);
 638         }
 639
 640         // Protected implementation of Dispose pattern.
 641         protected virtual void Dispose(bool disposing)
 642         {
 643             if (JSHandle < 0)
 644                 return;
 645
 646             if (disposing)
 647             {
 648
 649                 // Free any other managed objects here.
 650                 //
 651             }
 652
 653             // Free any unmanaged objects here.
 654             //
 655             FreeHandle();
 656         }
 657
 658         public override string ToString()
 659         {
 660             return $"(js-obj js '{JSHandle}' mono '{(IntPtr)Handle} raw '{RawObject != null})";
 661         }
 662
 663     }
 664
 665     public enum ConvertEnum
 666     {
 667         Default,
 668         ToLower,
 669         ToUpper,
 670         Numeric
 671     }
 672
 673     [AttributeUsage(AttributeTargets.Class | AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Field,
 674                     AllowMultiple = true, Inherited = false)]
 675     public class ExportAttribute : Attribute
 676     {
 677         public ExportAttribute() : this(null, null)
 678         {
 679         }
 680
 681         public ExportAttribute(Type contractType) : this(null, contractType)
 682         {
 683         }
 684
 685         public ExportAttribute(string contractName) : this(contractName, null)
 686         {
 687         }
 688
 689         public ExportAttribute(string contractName, Type contractType)
 690         {
 691             ContractName = contractName;
 692             ContractType = contractType;
 693         }
 694
 695         public string ContractName { get; }
 696
 697         public Type ContractType { get; }
 698         public ConvertEnum EnumValue { get; set; }
 699     }
 700
 701 }