Just as the adaptor mechanism is a poor man's ActiveX, the list adaptor is a poor man's Recordset (see ADO). I'm taking everything Microsoft does and doing it more simply. Eventually I'll put them right out of business.
These are the functions exposed by a list adaptor, with many more to come, I'm sure:
Function | Parameters | Purpose |
0: init | Initialize adaptor instance | |
1: free | Clean up instance before shutting down | |
2: info | Return XML describing the adaptor | |
3: create | List definition | Create a list. |
4: destroy | List definition | Destroy a list. |
5: add | List definition Object |
Add an object to a list. |
6: update | List definition Object |
Update an object. |
7: delete | List definition Key |
Delete an object. If no key given, deletes current object in list. |
8: get | List definition Key |
Retrieve an object. If no key given, retrieves the current object. |
9: query | List definition | Fills out the list definition with abbreviated records. |
10: first | List definition | Iterates through a list. Note that the list defn is used as a cursor. Don't use the original! |
11: next | List definition | Iterates. |
12: prev | List definition | Iterates. |
13: last | List definition | Iterates. |
14: keygen | List definition Object |
Builds a key from the object definition. |
15: attach_open | List definition Key Field name (optional) name of local file |
Opens an attachment stream for writing. The adaptor takes care of everything once the stream is closed. The localdir adaptor can use the name of local file to determine a filename for storage of the attachment (this makes it easy to treat, say, an images directory as a list with attachments.) The function returns a handle which can be decorated with a MIME type in content-type. |
16: attach_write | Buffer to read from size number Handle |
Writes data to an open attachment handle (like fwrite()) |
17: attach_close | Handle | Does the actual attachment; until attach_close is called, no effect is visible on the object. Among other things, the adaptor takes care of version control at this point. |
18: attach_cancel | Handle | Closes the attachment handle with no effect on the object and no embarrassment. |
19: retrieve_open | List definition Key Field name |
Opens an attachment (or any other field for that matter) for reading. The handle is XML and is decorated with attributes 'size' and 'content-type'. |
20: retrieve_read | Buffer to write to size number Handle |
Reads data from an open attachment retrieval handle (like fread()). |
21: retrieve_close | Handle. | Finishes a retrieval action. |
Implementations:
This code and documentation are released under the terms of the GNU license. They are additionally copyright (c) 2001, Vivtek. All rights reserved except those explicitly granted under the terms of the GNU license. This presentation was prepared with LPML. Try literate programming. You'll like it. |