--[[
  Generated with github.com/astrochili/defold-annotations
  Defold 1.10.2

  System API documentation

  Functions and messages for using system resources, controlling the engine,
  error handling and debugging.
--]]

---@meta
---@diagnostic disable: lowercase-global
---@diagnostic disable: missing-return
---@diagnostic disable: duplicate-doc-param
---@diagnostic disable: duplicate-set-field
---@diagnostic disable: args-after-dots

---@class defold_api.sys
sys = {}

---network connected through other, non cellular, connection
sys.NETWORK_CONNECTED = nil

---network connected through mobile cellular
sys.NETWORK_CONNECTED_CELLULAR = nil

---no network connection found
sys.NETWORK_DISCONNECTED = nil

---an asyncronous request is unable to read the resource
sys.REQUEST_STATUS_ERROR_IO_ERROR = nil

---an asyncronous request is unable to locate the resource
sys.REQUEST_STATUS_ERROR_NOT_FOUND = nil

---an asyncronous request has finished successfully
sys.REQUEST_STATUS_FINISHED = nil

---deserializes buffer into a lua table
---@param buffer string buffer to deserialize from
---@return table table lua table with deserialized data
function sys.deserialize(buffer) end

---Check if a path exists
---Good for checking if a file exists before loading a large file
---@param path string path to check
---@return bool result true if the path exists, false otherwise
function sys.exists(path) end

---Terminates the game application and reports the specified code to the OS.
---@param code number exit code to report to the OS, 0 means clean exit
function sys.exit(code) end

---Returns a table with application information for the requested app.
--- On iOS, the app_string is an url scheme for the app that is queried. Your
---game needs to list the schemes that are queried in an LSApplicationQueriesSchemes array
---in a custom "Info.plist".
--- On Android, the app_string is the package identifier for the app.
---@param app_string string platform specific string with application package or query, see above for details.
---@return { installed:boolean } app_info table with application information in the following fields:
---  
---  installed
---  boolean true if the application is installed, false otherwise.
---  
function sys.get_application_info(app_string) end

---The path from which the application is run.
---@return string path path to application executable
function sys.get_application_path() end

---Get integer config value from the game.project configuration file with optional default value
---@param key string key to get value for. The syntax is SECTION.KEY
---@param default_value? integer (optional) default value to return if the value does not exist
---@return integer value config value as an integer. default_value if the config key does not exist. 0 if no default value was supplied.
function sys.get_config_int(key, default_value) end

---Get number config value from the game.project configuration file with optional default value
---@param key string key to get value for. The syntax is SECTION.KEY
---@param default_value? number (optional) default value to return if the value does not exist
---@return number value config value as an number. default_value if the config key does not exist. 0 if no default value was supplied.
function sys.get_config_number(key, default_value) end

---Get string config value from the game.project configuration file with optional default value
---@param key string key to get value for. The syntax is SECTION.KEY
---@param default_value? string (optional) default value to return if the value does not exist
---@return string value config value as a string. default_value if the config key does not exist. nil if no default value was supplied.
function sys.get_config_string(key, default_value) end

---  Returns the current network connectivity status
---on mobile platforms.
---On desktop, this function always return sys.NETWORK_CONNECTED.
---@return constant status network connectivity status:
---  
---  sys.NETWORK_DISCONNECTED (no network connection is found)
---  sys.NETWORK_CONNECTED_CELLULAR (connected through mobile cellular)
---  sys.NETWORK_CONNECTED (otherwise, Wifi)
---  
function sys.get_connectivity() end

---Returns a table with engine information.
---@return { version:string, version_sha1:string, is_debug:boolean } engine_info table with engine information in the following fields:
---  
---  version
---  string The current Defold engine version, i.e. "1.2.96"
---  version_sha1
---  string The SHA1 for the current engine build, i.e. "0060183cce2e29dbd09c85ece83cbb72068ee050"
---  is_debug
---  boolean If the engine is a debug or release version
---  
function sys.get_engine_info() end

---Create a path to the host device for unit testing
---Useful for saving logs etc during development
---@param filename string file to read from
---@return string host_path the path prefixed with the proper host mount
function sys.get_host_path(filename) end

---Returns an array of tables with information on network interfaces.
---@return { name:string, address:string|nil, mac:string|nil, up:boolean, running:boolean } ifaddrs an array of tables. Each table entry contain the following fields:
---  
---  name
---  string Interface name
---  address
---  string IP address.  might be nil if not available.
---  mac
---  string Hardware MAC address.  might be nil if not available.
---  up
---  boolean true if the interface is up (available to transmit and receive data), false otherwise.
---  running
---  boolean true if the interface is running, false otherwise.
---  
function sys.get_ifaddrs() end

---The save-file path is operating system specific and is typically located under the user's home directory.
---@param application_id string user defined id of the application, which helps define the location of the save-file
---@param file_name string file-name to get path for
---@return string path path to save-file
function sys.get_save_file(application_id, file_name) end

---Returns a table with system information.
---@param options? table optional options table
---  - ignore_secure boolean this flag ignores values might be secured by OS e.g. device_ident
---@return { device_model:string|nil, manufacturer:string|nil, system_name:string, system_version:string, api_version:string, language:string, device_language:string, territory:string, gmt_offset:number, device_ident:string|nil, user_agent:string|nil } sys_info table with system information in the following fields:
---  
---  device_model
---  string  Only available on iOS and Android.
---  manufacturer
---  string  Only available on iOS and Android.
---  system_name
---  string The system name: "Darwin", "Linux", "Windows", "HTML5", "Android" or "iPhone OS"
---  system_version
---  string The system OS version.
---  api_version
---  string The API version on the system.
---  language
---  string Two character ISO-639 format, i.e. "en".
---  device_language
---  string Two character ISO-639 format (i.e. "sr") and, if applicable, followed by a dash (-) and an ISO 15924 script code (i.e. "sr-Cyrl" or "sr-Latn"). Reflects the device preferred language.
---  territory
---  string Two character ISO-3166 format, i.e. "US".
---  gmt_offset
---  number The current offset from GMT (Greenwich Mean Time), in minutes.
---  device_ident
---  string This value secured by OS.  "identifierForVendor" on iOS.  "android_id" on Android. On Android, you need to add READ_PHONE_STATE permission to be able to get this data. We don't use this permission in Defold.
---  user_agent
---  string  The HTTP user agent, i.e. "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/602.4.8 (KHTML, like Gecko) Version/10.0.3 Safari/602.4.8"
---  
function sys.get_sys_info(options) end

---If the file exists, it must have been created by sys.save to be loaded.
---@param filename string file to read from
---@return table loaded lua table, which is empty if the file could not be found
function sys.load(filename) end

---The sys.load_buffer function will first try to load the resource
---from any of the mounted resource locations and return the data if
---any matching entries found. If not, the path will be tried
---as is from the primary disk on the device.
---In order for the engine to include custom resources in the build process, you need
---to specify them in the "custom_resources" key in your "game.project" settings file.
---You can specify single resource files or directories. If a directory is included
---in the resource list, all files and directories in that directory is recursively
---included:
---For example "main/data/,assets/level_data.json".
---@param path string the path to load the buffer from
---@return buffer_data buffer the buffer with data
function sys.load_buffer(path) end

---The sys.load_buffer function will first try to load the resource
---from any of the mounted resource locations and return the data if
---any matching entries found. If not, the path will be tried
---as is from the primary disk on the device.
---In order for the engine to include custom resources in the build process, you need
---to specify them in the "custom_resources" key in your "game.project" settings file.
---You can specify single resource files or directories. If a directory is included
---in the resource list, all files and directories in that directory is recursively
---included:
---For example "main/data/,assets/level_data.json".
---Note that issuing multiple requests of the same resource will yield
---individual buffers per request. There is no implic caching of the buffers
---based on request path.
---@param path string the path to load the buffer from
---@param status_callback fun(self, request_id, result) A status callback that will be invoked when a request has been handled, or an error occured. The result is a table containing:
---  
---  status
---  number The status of the request, supported values are:
---  
---  
---  resource.REQUEST_STATUS_FINISHED
---  resource.REQUEST_STATUS_ERROR_IO_ERROR
---  resource.REQUEST_STATUS_ERROR_NOT_FOUND
---  
---  
---  buffer
---  buffer If the request was successfull, this will contain the request payload in a buffer object, and nil otherwise. Make sure to check the status before doing anything with the buffer value!
---  
---@return resource_handle handle a handle to the request
function sys.load_buffer_async(path, status_callback) end

---Loads a custom resource. Specify the full filename of the resource that you want
---to load. When loaded, the file data is returned as a string.
---If loading fails, the function returns nil plus the error message.
---In order for the engine to include custom resources in the build process, you need
---to specify them in the "custom_resources" key in your "game.project" settings file.
---You can specify single resource files or directories. If a directory is included
---in the resource list, all files and directories in that directory is recursively
---included:
---For example "main/data/,assets/level_data.json".
---@param filename string resource to load, full path
---@return string|nil data loaded data, or nil if the resource could not be loaded
---@return string|nil error the error message, or nil if no error occurred
function sys.load_resource(filename) end

---Open URL in default application, typically a browser
---@param url string url to open
---@param attributes? table table with attributes
---  target
---  - string : Optional. Specifies the target attribute or the name of the window. The following values are supported:
---  - _self - (default value) URL replaces the current page.
---  - _blank - URL is loaded into a new window, or tab.
---  - _parent - URL is loaded into the parent frame.
---  - _top - URL replaces any framesets that may be loaded.
---  - name - The name of the window (Note: the name does not specify the title of the new window).
---@return boolean success a boolean indicating if the url could be opened or not
function sys.open_url(url, attributes) end

---Reboots the game engine with a specified set of arguments.
---Arguments will be translated into command line arguments. Calling reboot
---function is equivalent to starting the engine with the same arguments.
---On startup the engine reads configuration from "game.project" in the
---project root.
---@param arg1? string argument 1
---@param arg2? string argument 2
---@param arg3? string argument 3
---@param arg4? string argument 4
---@param arg5? string argument 5
---@param arg6? string argument 6
function sys.reboot(arg1, arg2, arg3, arg4, arg5, arg6) end

---The table can later be loaded by sys.load.
---Use sys.get_save_file to obtain a valid location for the file.
---Internally, this function uses a workspace buffer sized output file sized 512kb.
---This size reflects the output file size which must not exceed this limit.
---Additionally, the total number of rows that any one table may contain is limited to 65536
---(i.e. a 16 bit range). When tables are used to represent arrays, the values of
---keys are permitted to fall within a 32 bit range, supporting sparse arrays, however
---the limit on the total number of rows remains in effect.
---@param filename string file to write to
---@param table table lua table to save
---@return boolean success a boolean indicating if the table could be saved or not
function sys.save(filename, table) end

---The buffer can later deserialized by sys.deserialize.
---This method has all the same limitations as sys.save.
---@param table table lua table to serialize
---@return string buffer serialized data buffer
function sys.serialize(table) end

---Sets the host that is used to check for network connectivity against.
---@param host string hostname to check against
function sys.set_connectivity_host(host) end

---Set the Lua error handler function.
---The error handler is a function which is called whenever a lua runtime error occurs.
---@param error_handler fun(source, message, traceback) the function to be called on error
---  
---  source
---  string The runtime context of the error. Currently, this is always "lua".
---  message
---  string The source file, line number and error message.
---  traceback
---  string The stack traceback.
---  
function sys.set_error_handler(error_handler) end

---Set game update-frequency (frame cap). This option is equivalent to display.update_frequency in
---the "game.project" settings but set in run-time. If Vsync checked in "game.project", the rate will
---be clamped to a swap interval that matches any detected main monitor refresh rate. If Vsync is
---unchecked the engine will try to respect the rate in software using timers. There is no
---guarantee that the frame cap will be achieved depending on platform specifics and hardware settings.
---@param frequency number target frequency. 60 for 60 fps
function sys.set_update_frequency(frequency) end

---Set the vsync swap interval. The interval with which to swap the front and back buffers
---in sync with vertical blanks (v-blank), the hardware event where the screen image is updated
---with data from the front buffer. A value of 1 swaps the buffers at every v-blank, a value of
---2 swaps the buffers every other v-blank and so on. A value of 0 disables waiting for v-blank
---before swapping the buffers. Default value is 1.
---When setting the swap interval to 0 and having vsync disabled in
---"game.project", the engine will try to respect the set frame cap value from
---"game.project" in software instead.
---This setting may be overridden by driver settings.
---@param swap_interval number target swap interval.
function sys.set_vsync_swap_interval(swap_interval) end

return sys