1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2  * vim: set ts=8 sts=2 et sw=2 tw=80:
3  * This Source Code Form is subject to the terms of the Mozilla Public
4  * License, v. 2.0. If a copy of the MPL was not distributed with this
5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 
7 #ifndef js_experimental_CTypes_h
8 #define js_experimental_CTypes_h
9 
10 #include "mozilla/Attributes.h"  // MOZ_RAII
11 
12 #include <stddef.h>  // size_t
13 
14 #include "jstypes.h"  // JS_PUBLIC_API
15 
16 #include "js/TypeDecls.h"
17 
18 namespace JS {
19 
20 #ifdef JS_HAS_CTYPES
21 
22 /**
23  * Initialize the 'ctypes' object on a global variable 'obj'. The 'ctypes'
24  * object will be sealed.
25  */
26 extern JS_PUBLIC_API bool InitCTypesClass(JSContext* cx,
27                                           Handle<JSObject*> global);
28 
29 #endif  // JS_HAS_CTYPES
30 
31 /**
32  * The type of ctypes activity that is occurring.
33  */
34 enum class CTypesActivityType {
35   BeginCall,
36   EndCall,
37   BeginCallback,
38   EndCallback,
39 };
40 
41 /**
42  * The signature of a function invoked at the leading or trailing edge of ctypes
43  * activity.
44  */
45 using CTypesActivityCallback = void (*)(JSContext*, CTypesActivityType);
46 
47 /**
48  * Sets a callback that is run whenever js-ctypes is about to be used when
49  * calling into C.
50  */
51 extern JS_PUBLIC_API void SetCTypesActivityCallback(JSContext* cx,
52                                                     CTypesActivityCallback cb);
53 
54 class MOZ_RAII JS_PUBLIC_API AutoCTypesActivityCallback {
55  private:
56   JSContext* cx;
57   CTypesActivityCallback callback;
58   CTypesActivityType endType;
59 
60  public:
61   AutoCTypesActivityCallback(JSContext* cx, CTypesActivityType beginType,
62                              CTypesActivityType endType);
63 
~AutoCTypesActivityCallback()64   ~AutoCTypesActivityCallback() { DoEndCallback(); }
65 
DoEndCallback()66   void DoEndCallback() {
67     if (callback) {
68       callback(cx, endType);
69       callback = nullptr;
70     }
71   }
72 };
73 
74 #ifdef JS_HAS_CTYPES
75 
76 /**
77  * Convert a unicode string 'source' of length 'slen' to the platform native
78  * charset, returning a null-terminated string allocated with JS_malloc. On
79  * failure, this function should report an error.
80  */
81 using CTypesUnicodeToNativeFun = char* (*)(JSContext*, const char16_t*, size_t);
82 
83 /**
84  * Set of function pointers that ctypes can use for various internal functions.
85  * See JS::SetCTypesCallbacks below. Providing nullptr for a function is safe
86  * and will result in the applicable ctypes functionality not being available.
87  */
88 struct CTypesCallbacks {
89   CTypesUnicodeToNativeFun unicodeToNative;
90 };
91 
92 /**
93  * Set the callbacks on the provided 'ctypesObj' object. 'callbacks' should be a
94  * pointer to static data that exists for the lifetime of 'ctypesObj', but it
95  * may safely be altered after calling this function and without having
96  * to call this function again.
97  */
98 extern JS_PUBLIC_API void SetCTypesCallbacks(JSObject* ctypesObj,
99                                              const CTypesCallbacks* callbacks);
100 
101 #endif  // JS_HAS_CTYPES
102 
103 }  // namespace JS
104 
105 #endif  // js_experimental_CTypes_h
106