1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_HSTSWRITEFUNCTION 5Section: 3 6Source: libcurl 7Protocol: 8 - HTTP 9See-also: 10 - CURLOPT_HSTS (3) 11 - CURLOPT_HSTSWRITEDATA (3) 12 - CURLOPT_HSTSWRITEFUNCTION (3) 13 - CURLOPT_HSTS_CTRL (3) 14--- 15 16# NAME 17 18CURLOPT_HSTSWRITEFUNCTION - write callback for HSTS hosts 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25struct curl_hstsentry { 26 char *name; 27 size_t namelen; 28 unsigned int includeSubDomains:1; 29 char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */ 30}; 31 32struct curl_index { 33 size_t index; /* the provided entry's "index" or count */ 34 size_t total; /* total number of entries to save */ 35}; 36 37CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts, 38 struct curl_index *count, void *clientp); 39 40CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite); 41~~~ 42 43# DESCRIPTION 44 45Pass a pointer to your callback function, as the prototype shows above. 46 47This callback function gets called by libcurl repeatedly to allow the 48application to store the in-memory HSTS cache when libcurl is about to discard 49it. 50 51Set the *clientp* argument with the CURLOPT_HSTSWRITEDATA(3) option 52or it is NULL. 53When the callback is invoked, the *sts* pointer points to a populated 54struct: Read the hostname to 'name' (it is *namelen* bytes long and null 55terminated. The *includeSubDomains* field is non-zero if the entry matches 56subdomains. The *expire* string is a date stamp null-terminated string 57using the syntax YYYYMMDD HH:MM:SS. 58 59The callback should return *CURLSTS_OK* if it succeeded and is prepared to 60be called again (for another host) or *CURLSTS_DONE* if there is nothing 61more to do. It can also return *CURLSTS_FAIL* to signal error. 62 63This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to 64do that. 65 66# DEFAULT 67 68NULL - no callback. 69 70# EXAMPLE 71 72~~~c 73struct priv { 74 void *custom; 75}; 76 77static CURLSTScode hswr_cb(CURL *easy, struct curl_hstsentry *sts, 78 struct curl_index *count, void *clientp) 79{ 80 /* save the passed in HSTS data somewhere */ 81 return CURLSTS_OK; 82} 83 84int main(void) 85{ 86 CURL *curl = curl_easy_init(); 87 if(curl) { 88 struct priv my_stuff; 89 CURLcode res; 90 91 /* set HSTS read callback */ 92 curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hswr_cb); 93 94 /* pass in suitable argument to the callback */ 95 curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &my_stuff); 96 97 res = curl_easy_perform(curl); 98 } 99} 100~~~ 101 102# AVAILABILITY 103 104Added in 7.74.0 105 106# RETURN VALUE 107 108This returns CURLE_OK. 109