1# Interface changes 2 3## Proposed interface changes for future versions 4 5Interface changes from 1.10 to 1.11 and/or later versions - 6see also [this GitHub issue](https://github.com/civetweb/civetweb/issues/544). 7 8 9### Server interface 10 11#### S1: mg\_start / mg\_init\_library 12 13Calling mg\_init\_library is recommended before calling mg\_start. 14 15**Compatibility considerations:** 16Initially, mg\_init\_library will be called implicitly if it has 17not been called before mg\_start. 18If mg\_init\_library was not called, mg\_stop may leave memory leaks. 19 20**Required Actions:** 21Call mg\_init\_library manually to avoid a small memory leak when 22closing the server. 23 24 25#### S2: mg\_websocket\_write functions 26 27Calling mg\_lock\_connection is no longer called implicitly 28in mg\_websocket\_write functions. 29If you use websocket write functions them from two threads, 30you must call mg\_lock\_connection explicitly, just like for any 31other connection. 32 33This is an API harmonization issue. 34 35**Compatibility considerations:** 36If a websocket connection was used in only one thread, there is 37no incompatibility. If a websocket connection was used in multiple 38threads, the user has to add the mg\_lock\_connection before and 39the mg\_unlock\_connection after the websocket write call. 40 41**Required Actions:** 42Call mg\_lock\_connection and mg\_unlock\_connection manually 43when using mg\_websocket\_write. 44 45 46#### S3: open\_file member of mg\_callbacks 47 48Memory mapped files are a relic from before `mg_set_request_handler` 49was introduced in CivetWeb 1.4 (September 2013). 50Is "file in memory" still a useful feature or dead code? See this 51[discussion](https://groups.google.com/forum/#!topic/civetweb/h9HT4CmeYqI). 52Since it is not widely used, and a burden in maintenance, the 53"file in memory" should be completely removed, including removing 54the open\_file member of mg\_callbacks. 55 56 57**Compatibility considerations:** 58Removing "file in memory" will require code using open\_file to be changed. 59A possible replacement by mg\_set\_request\_handler is sketched in 60[this comment](https://github.com/civetweb/civetweb/issues/440#issuecomment-290531238). 61 62**Required Actions:** 63Modify code using open\_file by using request handlers. 64 65 66#### S4: Support multiple hostnames and SNI 67 68TLS [Server Name Identification (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) 69allows to host different domains with different X.509 certificates 70on the same physical server (same IP+port). In order to support this, 71some configurations (like authentication\_domain, ssl\_certificate, 72document\_root and may others) need to be specified multiple times - 73once for each domain hosted 74(see [535](https://github.com/civetweb/civetweb/issues/535)). 75 76The current configuration model does not account for SNI, so it needs 77to be extended to support configuration of multiple instances. 78 79**Compatibility considerations:** 80To be defined as soon as possible solutions are evaluated. 81 82 83#### S5: IPv6 support for access\_control\_list and throttle 84 85The current configuration for access\_control\_list and throttle only 86works for IPv4 addresses. If server and client support 87[IPv6](https://en.wikipedia.org/wiki/IPv6_address) as well, 88there is no way to add a client to the throttle or access list. 89The current configuration syntax isn't really comfortable for IPv4 90either. 91Combined with hosting multiple domains (and SNI), different domains 92may have different block/throttle configurations as well - this has 93to be considered in a new configuration as well. 94 95**Compatibility considerations:** 96To be defined as soon as possible solutions are evaluated. 97 98 99### Client interface 100 101#### C1: mg\_init\_library 102 103Calling mg\_init\_library is required before calling any client 104function. In particular, the TLS initialization must be done 105before using mg\_connect\_client\_secure. 106 107**Compatibility considerations:** 108Some parts of the client interface did not work, if mg\_start 109was not called before. Now it works after calling 110mg\_init\_library - this is not an incompatibility. 111 112 113#### C2: mg\_connect\_client (family) 114 115mg\_connect\_client needs several new parameters (options). 116 117Details are to be defined. 118 119mg\_connect\_client and mg\_download should return a different kind of 120mg_connection than used in server callbacks. At least, there should 121be a function mg\_get\_response\_info, instead of using 122mg\_get\_request\_info, and getting the HTTP response code from the 123server by looking into the uri member of struct mg\_request\_info. 124 125 126### General interfaces 127 128#### G1: `size_t` in all interface 129 130Having `size_t` in interfaces while building for 32 and 64 bit 131complicates maintenance in an unnecessary way 132(see [498](https://github.com/civetweb/civetweb/issues/498)). 133 134Replace all data sizes by 64 bit integers. 135 136 137#### G2: Pattern definition 138 139The current definition of pattern matching is problematic 140(see [499](https://github.com/civetweb/civetweb/issues/499)). 141 142Find and implement a new definition. 143 144 145
