API for the new dispense ------------------------- New dispense is written in entirely in postgresql. The server does all the required processing, meaning that database integrity is always maintained. The current interface for dispense is using a postgresql client library. Client libraries exist for many languages including C, C++, Perl, Python, Ruby, PHP, or you could also speak with the supplied client 'psql' through stdin/stdout. The details for connecting to the database are: hostname: dispense.ucc.gu.uwa.edu.au username: anondispense database: dispense No password is required. You will only be able to connect from 'trusted' machines - currently this is mussel, mermaid, morwong. Note the API still isn't stable - it'd be worth running these commands by hand to see what the resulting tables look like. The useful things can be done once connected: - SELECT * FROM get_services(username) will give you a list of services available to the given user, including syntax if parameters are required - SELECT get_balance() will return a table of all users and their balances. - SELECT get_balance(username) will return a table with one row for the given user, displaying their account balance. - SELECT do_request(target_user, service_name, parameters) will perform a request. * target_user is the user you wish to perform the request upon. You will only be permitted to act on somebody else if you are in the coke group. * service_name is the name of the service as seen in the services table. * parameters is an array of parameters for the service, if required. These should appear in the order as item_syntax from the services table. Example follows: $ psql dispense -U anondispense -h dispense.ucc.gu.uwa.edu.au \Welcome to psql 7.4.1, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help on internal slash commands \g or terminate with semicolon to execute query \q to quit -- Equivalent of bringing up the menu. Only items allowed for -- the given user are shown. dispense=> select * from get_services('dagobah'); item_name | item_cost_cents | item_syntax | item_stock -------------+-----------------+--------------------------------------+------------ nothing | | | give | | | acct | | | passion pop | 80 | | 8 vb | 80 | | 0 emu export | 80 | | 3 champagne | 80 | | 9 coke powder | 80 | | 11 update_coke | | | opendoor | | | grape juice | 80 | | 0 some foo | 77 | | 3 (12 rows) -- Get balance for a user. -- Equivalent of 'dispense acct dagobah' -- Calling just get_balance() will return all users balances. dispense=> select * from get_balance('dagobah'); user_name | user_balance_cents | user_balance_bytes -----------+--------------------+-------------------- dagobah | -5080 | 0 (1 row) -- Dispense something for a user. -- Equivalent of 'dispense -u dagobah grape juice' dispense=> select do_request('dagobah', 'grape juice', NULL); ERROR: You may not dispense below -$20.00. CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement -- Adjust somebody's account balance up or down. -- Equivalent of 'dispense acct dagobah +10000 BAG123' dispense=> select do_request('dagobah', 'acct', array['+10000', 'BAG123']); do_request ------------ t (1 row) -- Get the balance once again ... note that it's higher :) dispense=> select * from get_balance('dagobah'); user_name | user_balance_cents | user_balance_bytes -----------+--------------------+-------------------- dagobah | 4920 | 0 (1 row) -- Try that dispense again, but we see there is none dispense=> select do_request('dagobah', 'grape juice', NULL); ERROR: We are out of stock of that item. CONTEXT: PL/pgSQL function "do_request" line 12 at SQL statement -- Try that dispense again, but we see there is none dispense=> select do_request('dagobah', 'some foo', NULL); do_request ------------ t (1 row) -- Updating a slot name/price on the coke machine dispense=> select do_request('dagobah', 'update_coke', array['3', 'orange blah', '88']); do_request ------------ t (1 row) -- Note the services have changed dispense=> select * from get_services('dagobah'); item_name | item_cost_cents | item_syntax | item_stock -------------+-----------------+--------------------------------------+------------ nothing | | | give | | | acct | | | passion pop | 80 | | 8 vb | 80 | | 0 emu export | 80 | | 3 champagne | 80 | | 9 coke powder | 80 | | 11 update_coke | | | opendoor | | | grape juice | 80 | | 0 orange blah | 88 | | 3 (12 rows) Email comments or queries to