From 1fdafb6abf2d3ea0d37e79b5dfd9daf8eed28f22 Mon Sep 17 00:00:00 2001 From: Simon Tatham Date: Sat, 30 Mar 2013 16:59:18 +0000 Subject: [PATCH] Add documentation for the identify_game() function which I introduced in r9749 and forgot to write up. [originally from svn r9777] [r9749 == 6b6442b16c5de9f5f9479b736bf865a4236047cb] --- devel.but | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/devel.but b/devel.but index 970a73a..9668651 100644 --- a/devel.but +++ b/devel.but @@ -3230,6 +3230,35 @@ would be pretty easy to write a function which would look at a save file and determine which game it was for; any front end implementor who needs such a function can probably be accommodated.) +\H{identify-game} \cw{identify_game()} + +\c char *identify_game(char **name, +\c int (*read)(void *ctx, void *buf, int len), +\c void *rctx) + +This function examines a serialised midend stream, of the same kind +used by \cw{midend_serialise()} and \cw{midendd_deserialise()}, and +returns the \cw{name} field of the game back end from which it was +saved. + +You might want this if your front end was a monolithic one containing +all the puzzles, and you wanted to be able to load an arbitrary save +file and automatically switch to the right game. Probably your next +step would be to iterate through \cw{gamelist} (\k{frontend-backend}) +looking for a game structure whose \cw{name} field matched the +returned string, and give an error if you didn't find one. + +On success, the return value of this function is \cw{NULL}, and the +game name string is written into \cw{*name}. The caller should free +that string after using it. + +On failure, \cw{*name} is \cw{NULL}, and the return value is an error +message (which does not need freeing at all). + +(This isn't strictly speaking a midend function, since it doesn't +accept or return a pointer to a midend. You'd probably call it just +\e{before} deciding what kind of midend you wanted to instantiate.) + \H{frontend-backend} Direct reference to the back end structure by the front end