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