common.h File

Included Headers

#include "qar_streaming.h" #include <inttypes.h> #include <stdbool.h> #include <stdio.h> #include <stdlib.h> #include <string.h>

Functions Index

static int	example_obtain_session (QarRuntime *runtime, const char *pairing_code, const char *id_file_path, const char *display_name, QarOnboardingId *out_onboarding_id, QarSession **out_session)
	[example_onboarding_persistence] More...
static const char *	get_dir_from_path (const char *path, char *out_dir, size_t out_sz)
	[example_obtain_session] More...
static bool	load_onboarding_id (const char *path, QarOnboardingId *out_id)
	[example_onboarding_persistence] More...
static void	log_result (const char *label, QarResult r)
	Log a QarResult with a label to stdout. More...
static void	print_hex_id (const uint8_t *data, size_t len)
	Print a fixed-size identifier as hex bytes separated by colons. More...
static void	save_onboarding_id (const char *path, const QarOnboardingId *id)
	Persist an onboarding id (UUID text) so the next run can rejoin. More...

Functions

example_obtain_session()

int example_obtain_session (QarRuntime * runtime, const char * pairing_code, const char * id_file_path, const char * display_name, QarOnboardingId * out_onboarding_id, QarSession ** out_session)

static

[example_onboarding_persistence]

[example_obtain_session]

Obtain a session the canonical way: rejoin with the persisted onboarding id when one exists, otherwise onboard with the pairing code currently shown on the hub's onboarding screen.

Returns 0 on success; on success *out_session and *out_onboarding_id are set and the id has been persisted to id_file_path for the next run.

Definition at line 91 of file common.h.

get_dir_from_path()

const char * get_dir_from_path (const char * path, char * out_dir, size_t out_sz)

static

[example_obtain_session]

Extract directory portion from a path (both '/' and '\' on Windows).

Definition at line 169 of file common.h.

load_onboarding_id()

bool load_onboarding_id (const char * path, QarOnboardingId * out_id)

static

[example_onboarding_persistence]

Load a persisted onboarding id (UUID text) from a small state file. Returns false when the file does not exist yet (first run).

Definition at line 43 of file common.h.

log_result()

void log_result (const char * label, QarResult r)

static

Log a QarResult with a label to stdout.

Definition at line 25 of file common.h.

print_hex_id()

void print_hex_id (const uint8_t * data, size_t len)

static

Print a fixed-size identifier as hex bytes separated by colons.

Definition at line 11 of file common.h.

save_onboarding_id()

void save_onboarding_id (const char * path, const QarOnboardingId * id)

static

Persist an onboarding id (UUID text) so the next run can rejoin.

Definition at line 64 of file common.h.

File Listing

The file content with the documentation metadata removed is:

1#pragma once

2#include "qar_streaming.h"

3#include <inttypes.h>

4#include <stdbool.h>

5#include <stdio.h>

6#include <stdlib.h>

7#include <string.h>

8

9/** \brief Print a fixed-size identifier as hex bytes separated by colons. */

10static void

11print_hex_id(const uint8_t* data, size_t len)

12{

13 for(size_t i = 0; i < len; ++i)

14 {

15 printf("%02X", (unsigned)data[i]);

16 if(i + 1 < len)

17 {

18 printf(":");

19 }

20 }

21}

22

23/** \brief Log a \ref QarResult with a label to stdout. */

24static void

25log_result(const char* label, QarResult r)

26{

27 if(qar_result_is_success(r))

28 {

29 printf("%s: SUCCESS (code=%d)\n", label, (int)r.code);

30 }

31 else

32 {

33 char msg[256] = { 0 };

34 qar_result_message(r, msg, sizeof(msg));

35 printf("%s: ERROR (code=%d) msg='%s'\n", label, (int)r.code, msg);

36 }

37}

38

39//! [example_onboarding_persistence]

40/** \brief Load a persisted onboarding id (UUID text) from a small state file.

41 * Returns false when the file does not exist yet (first run). */

42static bool

43load_onboarding_id(const char* path, QarOnboardingId* out_id)

44{

45 FILE* file = fopen(path, "r");

46 if(!file)

47 {

48 return false;

49 }

50 char text[64] = { 0 };

51 const bool read_ok = fgets(text, sizeof(text), file) != NULL;

52 fclose(file);

53 if(!read_ok)

54 {

55 return false;

56 }

57 text[strcspn(text, "\r\n")] = '\0';

58 QarResult parse_result = qar_uuid_from_string(text, out_id->data);

59 return qar_result_is_success(parse_result);

60}

61

62/** \brief Persist an onboarding id (UUID text) so the next run can rejoin. */

63static void

64save_onboarding_id(const char* path, const QarOnboardingId* id)

65{

66 char text[64] = { 0 };

67 if(qar_result_is_error(qar_uuid_to_string(id->data, text, sizeof(text))))

68 {

69 printf("Failed to serialize onboarding id\n");

70 return;

71 }

72 FILE* file = fopen(path, "w");

73 if(!file)

74 {

75 printf("Failed to persist onboarding id to '%s'\n", path);

76 return;

77 }

78 fprintf(file, "%s\n", text);

79 fclose(file);

80}

81//! [example_onboarding_persistence]

82

83//! [example_obtain_session]

84/** \brief Obtain a session the canonical way: rejoin with the persisted

85 * onboarding id when one exists, otherwise onboard with the pairing code

86 * currently shown on the hub's onboarding screen.

87 *

88 * Returns 0 on success; on success *out_session and *out_onboarding_id are

89 * set and the id has been persisted to id_file_path for the next run. */

90static int

91example_obtain_session(

92 QarRuntime* runtime,

93 const char* pairing_code, /* may be NULL when a persisted id exists */

94 const char* id_file_path,

95 const char* display_name,

96 QarOnboardingId* out_onboarding_id,

97 QarSession** out_session

98)

99{

100 QarPeerPresentation presentation = qar_peer_presentation_default();

101 presentation.display_name = display_name;

102

103 /* 1 Silent rejoin with the persisted identity — the normal path. */

104 QarOnboardingId saved_id = qar_onboarding_id_default();

105 if(load_onboarding_id(id_file_path, &saved_id))

106 {

107 QarRejoinInit rejoin_init = qar_rejoin_init_default();

108 rejoin_init.onboarding_id = saved_id;

109 rejoin_init.presentation = presentation;

110

111 QarResult rejoin_result =

112 qar_runtime_rejoin(runtime, &rejoin_init, NULL, NULL, NULL, out_session);

113 log_result("qar_runtime_rejoin", rejoin_result);

114 if(qar_result_is_success(rejoin_result))

115 {

116 *out_onboarding_id = saved_id;

117 return 0;

118 }

119 if(!qar_result_has_code(rejoin_result, QAR_STATUS_ONBOARDING_SESSION_NOT_FOUND))

120 {

121 return 1; /* real error (hub unreachable, ...) */

122 }

123 /* No persisted slot for the id -> fall through to onboarding. */

124 }

125

126 /* 2 First connect: onboard with the code shown by the hub. */

127 if(!pairing_code)

128 {

129 printf(

130 "No persisted onboarding id in '%s'. Pass the pairing code shown "

131 "on the hub's onboarding screen.\n",

132 id_file_path

133 );

134 return 1;

135 }

136

137 QarOnboardInit onboard_init = qar_onboard_init_default();

138 QarOnboardCodeExt onboard_code = qar_onboard_code_ext_default();

139 onboard_init.presentation = presentation;

140 onboard_code.code = pairing_code;

141 onboard_init.header.next = &onboard_code.header;

142

143 QarOnboardingId new_id = qar_onboarding_id_default();

144 QarResult onboard_result =

145 qar_runtime_onboard(runtime, &onboard_init, NULL, NULL, NULL, &new_id, out_session);

146 log_result("qar_runtime_onboard", onboard_result);

147 if(qar_result_is_error(onboard_result))

148 {

149 if(qar_result_has_code(onboard_result, QAR_STATUS_PAKE_ERROR))

150 {

151 printf(

152 "Pairing code rejected or expired — read the current code "

153 "off the hub screen and retry.\n"

154 );

155 }

156 return 1;

157 }

158

159 /* 3 Persist the id — it is the ticket for every later rejoin/forget. */

160 save_onboarding_id(id_file_path, &new_id);

161 *out_onboarding_id = new_id;

162 return 0;

163}

164//! [example_obtain_session]

165

166/** \brief Extract directory portion from a path (both '/' and '\\' on Windows).

167 */

168static const char*

169get_dir_from_path(const char* path, char* out_dir, size_t out_sz)

170{

171 if(!path || !out_dir || out_sz == 0)

172 {

173 return NULL;

174 }

175 size_t n = strlen(path);

176 size_t i = n;

177 while(i > 0)

178 {

179 char c = path[i - 1];

180 if(c == '/' || c == '\\')

181 {

182 break;

183 }

184 --i;

185 }

186 if(i == 0)

187 {

188 // No separator found; use current directory

189 snprintf(out_dir, out_sz, ".");

190 return out_dir;

191 }

192 size_t dir_len = (i > out_sz - 1) ? (out_sz - 1) : i;

193 memcpy(out_dir, path, dir_len);

194 out_dir[dir_len] = '\0';

195 return out_dir;

196}

---

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.9.8.