1 // This file is part of Freecell Solver. It is subject to the license terms in
2 // the COPYING.txt file found in the top-level directory of this distribution
3 // and at http://fc-solve.shlomifish.org/docs/distro/COPYING.html . No part of
4 // Freecell Solver, including this file, may be copied, modified, propagated,
5 // or distributed except according to the terms contained in the COPYING file.
6 //
7 // Copyright (c) 2000 Shlomi Fish
8 // fcs_user.h - main header file for the Freecell Solver library.
9 #pragma once
10 #include <stddef.h>
11 
12 #include "freecell-solver/fcs_dllexport.h"
13 #include "freecell-solver/fcs_enums.h"
14 #include "freecell-solver/fcs_move.h"
15 #include "freecell-solver/fcs_limit.h"
16 #include "freecell-solver/fcs_pats_xy_param.h"
17 #include "freecell-solver/fcs_back_compat.h"
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 #ifdef FC_SOLVE_STRINGS_COMPAT
24 typedef char *freecell_solver_str_t;
25 #else
26 typedef const char *freecell_solver_str_t;
27 #endif
28 
29 DLLEXPORT extern void *freecell_solver_user_alloc(void);
30 
31 DLLEXPORT extern int freecell_solver_user_apply_preset(
32     void *instance, const char *preset_name);
33 
34 DLLEXPORT extern void freecell_solver_user_limit_iterations_long(
35     void *user_instance, fcs_int_limit_t max_iters);
36 
37 void DLLEXPORT freecell_solver_user_soft_limit_iterations_long(
38     void *api_instance, fcs_int_limit_t max_iters);
39 
40 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
41 DLLEXPORT extern void freecell_solver_user_limit_iterations(
42     void *user_instance, int max_iters);
43 
44 DLLEXPORT extern int freecell_solver_user_set_tests_order(void *user_instance,
45     const char *moves_order FCS__PASS_ERR_STR(char **error_string));
46 #endif
47 
48 DLLEXPORT extern int freecell_solver_user_solve_board(
49     void *user_instance, const char *state_as_string);
50 
51 DLLEXPORT extern int freecell_solver_user_resume_solution(void *user_instance);
52 
53 DLLEXPORT extern int freecell_solver_user_get_next_move(
54     void *user_instance, fcs_move_t *move);
55 
56 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
57 DLLEXPORT extern char *freecell_solver_user_current_state_as_string(
58     void *user_instance
59 #ifndef FC_SOLVE_IMPLICIT_PARSABLE_OUTPUT
60     ,
61     int parseable_output
62 #endif
63     ,
64     int canonized_order_output
65 #ifndef FC_SOLVE_IMPLICIT_T_RANK
66     ,
67     int display_10_as_t
68 #endif
69 );
70 #endif
71 
72 DLLEXPORT extern void freecell_solver_user_current_state_stringify(
73     void *user_instance, char *const output_string
74 #ifndef FC_SOLVE_IMPLICIT_PARSABLE_OUTPUT
75     ,
76     int parseable_output
77 #endif
78     ,
79     int canonized_order_output
80 #ifndef FC_SOLVE_IMPLICIT_T_RANK
81     ,
82     int display_10_as_t
83 #endif
84 );
85 
86 DLLEXPORT extern void freecell_solver_user_free(void *user_instance);
87 
88 DLLEXPORT extern int freecell_solver_user_get_current_depth(
89     void *user_instance);
90 
91 DLLEXPORT extern void freecell_solver_user_set_solving_method(
92     void *const user_instance, const int method);
93 
94 DLLEXPORT extern fcs_iters_int freecell_solver_user_get_num_times_long(
95     void *user_instance);
96 
97 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
98 DLLEXPORT extern int freecell_solver_user_get_num_times(void *user_instance);
99 
100 DLLEXPORT extern int freecell_solver_user_get_limit_iterations(
101     void *user_instance);
102 #endif
103 
104 DLLEXPORT extern int freecell_solver_user_get_moves_left(void *user_instance);
105 
106 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
107 DLLEXPORT extern int freecell_solver_user_set_game(void *user_instance,
108     int freecells_num, int stacks_num, int decks_num,
109     int sequences_are_built_by, int unlimited_sequence_move,
110     int empty_stacks_fill);
111 #endif
112 
113 DLLEXPORT extern void freecell_solver_user_set_solution_optimization(
114     void *user_instance, int optimize);
115 
116 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
117 DLLEXPORT extern char *freecell_solver_user_move_to_string(
118     fcs_move_t move, int standard_notation);
119 
120 DLLEXPORT extern char *freecell_solver_user_move_to_string_w_state(
121     void *user_instance, fcs_move_t move, int standard_notation);
122 #endif
123 
124 DLLEXPORT extern void freecell_solver_user_stringify_move_w_state(
125     void *user_instance, char *output_string, fcs_move_t move,
126     int standard_notation);
127 
128 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
129 DLLEXPORT extern void freecell_solver_user_limit_depth(
130     void *user_instance, int max_depth);
131 #endif
132 
133 DLLEXPORT extern int freecell_solver_user_set_num_freecells(
134     void *user_instance, int freecells_num);
135 
136 DLLEXPORT extern int freecell_solver_user_get_max_num_freecells(void);
137 
138 DLLEXPORT extern int freecell_solver_user_set_num_stacks(
139     void *user_instance, int stacks_num);
140 
141 DLLEXPORT extern int freecell_solver_user_get_max_num_stacks(void);
142 
143 DLLEXPORT extern int freecell_solver_user_set_num_decks(
144     void *user_instance, int decks_num);
145 
146 DLLEXPORT extern int freecell_solver_user_get_max_num_decks(void);
147 
148 #ifdef FCS_WITH_ERROR_STRS
149 DLLEXPORT void freecell_solver_user_get_invalid_state_error_into_string(
150     void *const api_instance, char *const string
151 #ifndef FC_SOLVE_IMPLICIT_T_RANK
152     ,
153     const int print_ts
154 #endif
155 );
156 #endif
157 
158 #ifdef FCS_WITH_ERROR_STRS
159 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
160 DLLEXPORT extern char *freecell_solver_user_get_invalid_state_error_string(
161     void *user_instance
162 #ifndef FC_SOLVE_IMPLICIT_T_RANK
163     ,
164     int print_ts
165 #endif
166 );
167 #endif
168 #endif
169 
170 DLLEXPORT extern int freecell_solver_user_set_sequences_are_built_by_type(
171     void *user_instance, int sequences_are_built_by);
172 
173 DLLEXPORT extern int freecell_solver_user_set_empty_stacks_filled_by(
174     void *user_instance, int es_fill);
175 
176 DLLEXPORT extern int freecell_solver_user_set_sequence_move(
177     void *user_instance, int unlimited_sequence_move);
178 
179 DLLEXPORT extern int freecell_solver_user_set_a_star_weight(
180     void *const user_instance, const int my_index, const double weight);
181 
182 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
183 typedef void (*freecell_solver_user_iter_handler_t)(void *user_instance,
184     int iter_num, int depth, void *ptr_state, int parent_iter_num,
185     void *context);
186 #endif
187 
188 typedef void (*freecell_solver_user_long_iter_handler_t)(void *user_instance,
189     fcs_int_limit_t iter_num, int depth, void *ptr_state,
190     fcs_int_limit_t parent_iter_num, void *context);
191 
192 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
193 DLLEXPORT extern void freecell_solver_user_set_iter_handler(void *user_instance,
194     freecell_solver_user_iter_handler_t iter_handler,
195     void *iter_handler_context);
196 #endif
197 
198 DLLEXPORT extern void freecell_solver_user_set_iter_handler_long(
199     void *user_instance, freecell_solver_user_long_iter_handler_t iter_handler,
200     void *iter_handler_context);
201 
202 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
203 DLLEXPORT extern char *freecell_solver_user_iter_state_as_string(
204     void *const user_instance, void *const ptr_state
205 #ifndef FC_SOLVE_IMPLICIT_PARSABLE_OUTPUT
206     ,
207     const int parseable_output
208 #endif
209     ,
210     const int canonized_order_output
211 #ifndef FC_SOLVE_IMPLICIT_T_RANK
212     ,
213     const int display_10_as_t
214 #endif
215 );
216 #endif
217 
218 DLLEXPORT extern void freecell_solver_user_iter_state_stringify(
219     void *const user_instance, char *output_string, void *const ptr_state
220 #ifndef FC_SOLVE_IMPLICIT_PARSABLE_OUTPUT
221     ,
222     const int parseable_output
223 #endif
224     ,
225     const int canonized_order_output
226 #ifndef FC_SOLVE_IMPLICIT_T_RANK
227     ,
228     const int display_10_as_t
229 #endif
230 );
231 
232 DLLEXPORT extern void freecell_solver_user_set_random_seed(
233     void *const user_instance, const int seed);
234 
235 #ifndef FCS_DISABLE_NUM_STORED_STATES
236 DLLEXPORT fcs_int_limit_t
237 freecell_solver_user_get_num_states_in_collection_long(
238     void *const user_instance);
239 
240 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
241 DLLEXPORT extern int freecell_solver_user_get_num_states_in_collection(
242     void *const user_instance);
243 #endif
244 
245 DLLEXPORT extern void freecell_solver_user_limit_num_states_in_collection_long(
246     void *user_instance, fcs_int_limit_t max_num_states);
247 
248 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
249 DLLEXPORT extern void freecell_solver_user_limit_num_states_in_collection(
250     void *user_instance, int max_num_states);
251 #endif
252 
253 DLLEXPORT extern void freecell_solver_set_stored_states_trimming_limit(
254     void *user_instance, long max_num_states);
255 #endif
256 
257 DLLEXPORT extern int freecell_solver_user_next_soft_thread(void *user_instance);
258 
259 DLLEXPORT extern void freecell_solver_user_set_soft_thread_step(
260     void *const user_instance, const int checked_states_step);
261 
262 DLLEXPORT extern int freecell_solver_user_next_hard_thread(
263     void *const user_instance);
264 
265 DLLEXPORT extern int freecell_solver_user_get_num_soft_threads_in_instance(
266     void *const user_instance);
267 
268 DLLEXPORT extern void freecell_solver_user_set_calc_real_depth(
269     void *const user_instance, const int calc_real_depth);
270 
271 DLLEXPORT extern void freecell_solver_user_set_soft_thread_name(
272     void *const user_instance, freecell_solver_str_t name);
273 
274 DLLEXPORT extern void freecell_solver_user_set_flare_name(
275     void *const user_instance, freecell_solver_str_t name);
276 
277 DLLEXPORT extern int freecell_solver_user_set_hard_thread_prelude(
278     void *const user_instance, freecell_solver_str_t prelude);
279 
280 DLLEXPORT extern int freecell_solver_user_set_flares_plan(
281     void *const api_instance, freecell_solver_str_t plan);
282 
283 DLLEXPORT extern void freecell_solver_user_recycle(void *const user_instance);
284 
285 DLLEXPORT extern int freecell_solver_user_set_optimization_scan_tests_order(
286     void *const user_instance,
287     const char *const moves_order FCS__PASS_ERR_STR(char **const error_string));
288 
289 DLLEXPORT extern void freecell_solver_user_set_reparent_states(
290     void *const user_instance, const int to_reparent_states);
291 
292 DLLEXPORT extern void freecell_solver_user_set_scans_synergy(
293     void *const user_instance, const int synergy);
294 
295 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
296 DLLEXPORT extern void freecell_solver_user_limit_current_instance_iterations(
297     void *user_instance, int max_iters);
298 #endif
299 
300 DLLEXPORT extern int freecell_solver_user_next_instance(
301     void *const user_instance);
302 
303 DLLEXPORT extern int freecell_solver_user_next_flare(void *const api_instance);
304 
305 // This function resets the user_instance, making it lose
306 // all the previous command line arguments it encountered
307 #ifndef FCS_BREAK_BACKWARD_COMPAT_1
308 DLLEXPORT extern int freecell_solver_user_reset(void *const user_instance);
309 
310 DLLEXPORT const char *freecell_solver_user_get_lib_version(
311     void *const user_instance);
312 #endif
313 
314 DLLEXPORT const char *freecell_solver_user_get_current_soft_thread_name(
315     void *const user_instance);
316 
317 // This error string should be strdup()'ed or else copied if one wishes
318 // to reuse it. Otherwise, it should be treated as constant.
319 #ifdef FCS_WITH_ERROR_STRS
320 DLLEXPORT const char *freecell_solver_user_get_last_error_string(
321     void *const api_instance);
322 #endif
323 
324 // This sets the moves_order from min_depth onwards.
325 DLLEXPORT extern int freecell_solver_user_set_depth_tests_order(
326     void *const user_instance, const int min_depth,
327     const char *const moves_order FCS__PASS_ERR_STR(char **const error_string));
328 
329 #ifndef FCS_ENABLE_PRUNE__R_TF__UNCOND
330 DLLEXPORT extern int freecell_solver_user_set_pruning(void *const user_instance,
331     const char *const pruning FCS__PASS_ERR_STR(char **const error_string));
332 #endif
333 
334 DLLEXPORT extern int freecell_solver_user_set_cache_limit(
335     void *const user_instance, long limit);
336 
337 DLLEXPORT extern int freecell_solver_user_get_moves_sequence(
338     void *const user_instance, fcs_moves_sequence_t *const moves_seq);
339 
340 DLLEXPORT extern int freecell_solver_user_set_flares_choice(
341     void *const user_instance, const char *const new_flares_choice_string);
342 
343 DLLEXPORT extern void freecell_solver_user_set_flares_iters_factor(
344     void *const user_instance, const double new_factor);
345 
346 DLLEXPORT extern int freecell_solver_user_set_patsolve_x_param(
347     void *const api_instance, const int position,
348     const int x_param_val FCS__PASS_ERR_STR(char **const error_string));
349 
350 DLLEXPORT extern int freecell_solver_user_set_patsolve_y_param(
351     void *const api_instance, const int position,
352     const double y_param_val FCS__PASS_ERR_STR(char **const error_string));
353 
354 typedef struct
355 {
356     size_t scan_idx;
357     size_t quota;
358 } fc_solve_prelude_item;
359 
360 DLLEXPORT extern void fc_solve_user_set_ht_compiled_prelude(
361     void *, size_t, const fc_solve_prelude_item *);
362 
363 int DLLEXPORT freecell_solver_user_set_unrecognized_cmd_line_flag(
364     void *const api_instance, const int flag_idx, const char *val);
365 
366 DLLEXPORT char *freecell_solver_user_get_unrecognized_cmd_line_flag(
367     void *, int);
368 
369 typedef enum
370 {
371     FC_SOLVE__FLAG_STATUS__ERROR = -1,
372     FC_SOLVE__FLAG_STATUS__VALID = 0,
373     FC_SOLVE__FLAG_STATUS__IS_NULL = 1,
374 } fc_solve_unrecognized_flag_status_type;
375 
376 DLLEXPORT fc_solve_unrecognized_flag_status_type
377 freecell_solver_user_get_unrecognized_cmd_line_flag_status(
378     void *const api_instance, const int flag_idx);
379 
380 #ifdef __cplusplus
381 }
382 #endif
383