The HTML (more readable) is at http://bang.dhs.org/comments.html
The lynx-rendered version follows (text wrapping is OFF on this mail):
Current client requirements
bool ReadTOC(CDINDEX_DEVICE device,
CDINDEX_CDINFO& cdinfo);
void LaunchBrowser(char* browser,
char* url);
void Usage();
Client must also define OS and is forced to typedef CDINDEX_DEVICE to
char*.
Suggested naming scheme
1. Standard C library as described at http://www.dinkum.com/htm_cl/
2. CDIndex_nocaps = type or enum
3. CDIndex_InterCaps = function name
Library stage 1 spec (per readme)
Comments on the readme:
> separated functionality for retrieving CD TOC information
> separated functionality for ID calculation
Why? These can be merged quite efficiently; it's not particularly
intensive to calculate a hash, and the TOC is useless to the cdindex
without the hash. As a bonus, that hash can be used in any
library-using applications for local caching.
> separated functionality for system identification ("the lib
> thinks it runs on foodows 2000")
I'm unclear who would be using this. Library platform-specific layer?
I can't see it being useful.
On to my proposal:
Platform layer changes:
LaunchBrowser() loses the "browser" parameter. Usage() eliminated.
Add:
bool parse_scsi_toc(uint8 *toc, int toc_length, bool uses_msf,
CDINDEX_CDINFO *);
... to make life easier on those OSes that use SCSI TOCs to describe a
CD to an applications.
Platform-independent layer:
// Picks a new device for CD accesses.
bool CDIndex_SetPreferredDevice(CDINDEX_DEVICE device);
struct CDIndex_toc {
uint8 FirstTrack; // The first track on CD : normally 1
uint8 LastTrack; // The last track on CD: max number 99
uint16 FrameOffset[100]; // Track n is FrameOffset[n] etc.
// Leadout track will be TrackFrameOffset
[0]
uint8 hash[20];
};
// Fills out the TOC structure from the preferred device.
bool CDIndex_GetTOC(CDINDEX_toc &cdinfo_out);
// The result of this function must be freed; behaviour=obvious
char *CDIndex_GetPrintableHash(CDINDEX_toc &cdinfo, int &hash_length_ou
t);
// Returns a URL that should describe the current CD.
// If "cdinfo" is null, it goes to the current CD in the drive.
// If "launch" = true, the browser will be launched, using the
// The result of this function must be freed.
char *CDIndex_GetURL(CDINDEX_toc *cdinfo, bool launch);
// This declares a preferred browser to the CDIndex library.
void CDIndex_SetPreferredBrowser(void (*CDIndex_LaunchURL)(char *url));
Library stage 2 spec:
Platform layer:
http://www-classic.be.com/documentation/be_book/The%20Network%20Kit/in
dex.html is used as a design reference.
CDIndex_Net_CONNECTION : platform-specific type
// Opens a network connection to a specific address:
// "cdindex.org" or "25.12.151.6".
CDIndex_Net_CONNECTION CDIndex_Net_CreateConnection(char *where);
// Returns the number of bytes sent or -1 on error.
int CDIndex_Net_SendData(CDIndex_NetConnetion , uint8 *data, int data_l
ength);
// Returns the number of bytes read or -1 on error.
// 0 is a valid return value!
// May or may not block.
int CDIndex_Net_ReadData(CDIndex_NetConnection, uint8 *buffer, int buff
er_length);
// Closes up a connection.
void CDIndex_Net_DisposeConnection(CDIndex_NetConnection *);
// Indicates the cause (in plain english) of the cause of the last erro
r.
// The return value must be free()d.
char *CDIndex_Net_GetErrorState(CDIndex_NetConnection *);
Platform-independent:
struct CDIndex_track {
char *name;
char *artist;
};
struct CDIndex_description {
int track_count;
char *title;
char *author;
CDIndex_Track *track_list;
};
void CDIndex_DisposeDescription(CDIndex_description *);
// Gets a description for the given toc.
// If toc==null, use current CD.
CDIndex_description *CDIndex_GetDescription(CDIndex_toc *toc);
Note: All the work of getting actual XML is done
platform-independently. All the work of parsing the XML into a
description is too.
Issue: The cdindex server currently bounces you around with a bunch of
HTTP redirects when you approach it with the URL given out by the
client app. There needs to be a guaranteed shortcut through all this
nonsense. I'd recommend making a non-HTTP protocol to pipe requests to
the web server (for query and submission). This should really not be
hard, at most a half hour's time with perl.