1 /// \file wasmtime/component/component.h 2 3 #ifndef WASMTIME_COMPONENT_COMPONENT_H 4 #define WASMTIME_COMPONENT_COMPONENT_H 5 6 #include <wasm.h> 7 #include <wasmtime/component/types/component.h> 8 #include <wasmtime/conf.h> 9 #include <wasmtime/error.h> 10 11 #ifdef WASMTIME_FEATURE_COMPONENT_MODEL 12 13 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /// Representation of a component in the component model. 18 typedef struct wasmtime_component_t wasmtime_component_t; 19 20 #ifdef WASMTIME_FEATURE_COMPILER 21 22 /** 23 * \brief Compiles a WebAssembly binary into a #wasmtime_component_t 24 * 25 * This function will compile a WebAssembly binary into an owned 26 #wasmtime_component_t. 27 * 28 * It requires a component binary, such as what is produced by Rust `cargo 29 component` tooling. 30 * 31 * This function does not take ownership of any of its arguments, but the 32 * returned error and component are owned by the caller. 33 34 * \param engine the #wasm_engine_t that will create the component 35 * \param buf the address of the buffer containing the WebAssembly binary 36 * \param len the length of the buffer containing the WebAssembly binary 37 * \param component_out on success, contains the address of the created 38 * component 39 * 40 * \return NULL on success, else a #wasmtime_error_t describing the error 41 */ 42 WASM_API_EXTERN wasmtime_error_t * 43 wasmtime_component_new(const wasm_engine_t *engine, const uint8_t *buf, 44 size_t len, wasmtime_component_t **component_out); 45 46 /** 47 * \brief This function serializes compiled component artifacts as blob data. 48 * 49 * \param component the component 50 * \param ret if the conversion is successful, this byte vector is filled in 51 * with the serialized compiled component. 52 * 53 * \return a non-null error if parsing fails, or returns `NULL`. If parsing 54 * fails then `ret` isn't touched. 55 * 56 * This function does not take ownership of `component`, and the caller is 57 * expected to deallocate the returned #wasmtime_error_t and #wasm_byte_vec_t. 58 */ 59 WASM_API_EXTERN wasmtime_error_t * 60 wasmtime_component_serialize(const wasmtime_component_t *component, 61 wasm_byte_vec_t *ret); 62 63 #endif // WASMTIME_FEATURE_COMPILER 64 65 /** 66 * \brief Build a component from serialized data. 67 * 68 * This function does not take ownership of any of its arguments, but the 69 * returned error and component are owned by the caller. 70 * 71 * This function is not safe to receive arbitrary user input. See the Rust 72 * documentation for more information on what inputs are safe to pass in here 73 * (e.g. only that of `wasmtime_component_serialize`) 74 */ 75 WASM_API_EXTERN wasmtime_error_t * 76 wasmtime_component_deserialize(const wasm_engine_t *engine, const uint8_t *buf, 77 size_t len, 78 wasmtime_component_t **component_out); 79 80 /** 81 * \brief Deserialize a component from an on-disk file. 82 * 83 * This function is the same as #wasmtime_component_deserialize except that it 84 * reads the data for the serialized component from the path on disk. This can 85 * be faster than the alternative which may require copying the data around. 86 * 87 * This function does not take ownership of any of its arguments, but the 88 * returned error and component are owned by the caller. 89 * 90 * This function is not safe to receive arbitrary user input. See the Rust 91 * documentation for more information on what inputs are safe to pass in here 92 * (e.g. only that of `wasmtime_component_serialize`) 93 */ 94 WASM_API_EXTERN wasmtime_error_t * 95 wasmtime_component_deserialize_file(const wasm_engine_t *engine, 96 const char *path, 97 wasmtime_component_t **component_out); 98 99 /** 100 * \brief Creates a shallow clone of the specified component, increasing the 101 * internal reference count. 102 */ 103 WASM_API_EXTERN wasmtime_component_t * 104 wasmtime_component_clone(const wasmtime_component_t *component); 105 106 /** 107 * \brief Returns the type of this component. 108 * 109 * The returned pointer must be deallocatd with 110 * `wasmtime_component_type_delete`. 111 */ 112 WASM_API_EXTERN wasmtime_component_type_t * 113 wasmtime_component_type(const wasmtime_component_t *component); 114 115 /** 116 * \brief Deletes a #wasmtime_component_t created by #wasmtime_component_new 117 * 118 * \param component the component to delete 119 */ 120 WASM_API_EXTERN void wasmtime_component_delete(wasmtime_component_t *component); 121 122 /// A value which represents a known export of a component. 123 typedef struct wasmtime_component_export_index_t 124 wasmtime_component_export_index_t; 125 126 /** 127 * \brief Looks up a specific export of this component by \p name optionally 128 * nested within the \p instance provided. 129 * 130 * \param component the component to look up \p name in 131 * \param instance_export_index optional (i.e. nullable) instance to look up in 132 * \param name the name of the export 133 * \param name_len length of \p name in bytes 134 * \return export index if found, else NULL 135 */ 136 WASM_API_EXTERN wasmtime_component_export_index_t * 137 wasmtime_component_get_export_index( 138 const wasmtime_component_t *component, 139 const wasmtime_component_export_index_t *instance_export_index, 140 const char *name, size_t name_len); 141 142 /** 143 * \brief Creates a new separately-owned copy of the specified index. 144 */ 145 WASM_API_EXTERN wasmtime_component_export_index_t * 146 wasmtime_component_export_index_clone( 147 const wasmtime_component_export_index_t *index); 148 149 /** 150 * \brief Deletes a #wasmtime_component_export_index_t 151 * 152 * \param export_index the export index to delete 153 */ 154 WASM_API_EXTERN void wasmtime_component_export_index_delete( 155 wasmtime_component_export_index_t *export_index); 156 157 #ifdef __cplusplus 158 } // extern "C" 159 #endif 160 161 #endif // WASMTIME_FEATURE_COMPONENT_MODEL 162 163 #endif // WASMTIME_COMPONENT_COMPONENT_H 164