17 posts
Posted 08 December 2012 - 09:59 AM
RealTime API
Get and format the time of a mysterious realm known as "the real world"
What can it do?
Spoiler
Included in the API are the following functions (see below for usage):
- getTime - Gets the current time from the server
- formatTime - Puts the time in a nicely formatted string that is ready to be displayed
- validateTime - Ensures that the given time is in the proper range. Also changes AM/PM if in 12 hour format
With these functions you can create a multitude of programs, such as the clock example below.
Functions
Spoiler
The required parameters and what the function returns are listed below:
getTime(timezone, format)
Arguments
timezone = [Number] The timezone you want the time in (ie. -5 for Eastern Time)
format = [Number] Return the hours in 24 or 12 hour format (ie. 12 would return 8 PM where 24 would return 20)
Returns
Return Format: Array
Index 1: current hours [Number]
Index 2: current minutes [Number]
Index 3: current seconds [Number]
Index 4 (only for 12 hour format): AM/PM [String]
formatTime(hours, minutes, seconds, format, validate, ampm)
Arguments
hours, minutes, seconds = [Number] Hours/Minutes/Seconds (can be retrieved using getTime) to format
format = [Number] If the time is in 12 or 24 hour format; used only if validate is 'true'
validate: [Boolean] Run the validateTime function to ensure proper range (ie. 'true' will run the function)
ampm: [String] Specifies wether the time is AM or PM; used only if 12 hour format is selected. Used only if validate is 'true'
Returns
Return Format: String
String Example: "5:47:09"
validateTime(hours, minutes, seconds, format, ampm)
Arguments
hours, minutes, seconds = [Number] Hours/Minutes/Seconds (can be retrieved using getTime) to format
format = [Number] If the time is in 12 or 24 hour format; used only if validate is 'true'
ampm: [String] Specifies wether the time is AM or PM; used only if 12 hour format is selected
Returns
Return Format: Array
Index 1: current hours [Number]
Index 2: current minutes [Number]
Index 3: current seconds [Number]
Index 4 (only for 12 hour format): AM/PM [String]
How Does it Work/What is Needed for it to Work?
Spoiler
Please note: For the getTime function to work, the HTTP API must be enabled in your ComputerCraft.cfg file!
To get the current time, the API reads the first line of a page that uses PHP to return the current time. The default site for this is http://www.timeapi.org/utc/now?format=%25I:%25M:%25S:%25Z. Also, I currently host a script at http://t3kbau5.tk/stuff/time.php.The script is just one line of PHP that returns the server time and timezone, allowing for conversions to other formats and timezones.
Downloads and Other Stuff
Spoiler
The download link below includes the API (with extension .api for easy reference), an example program (clock), and the PHP script (time.php) if you want to host it on your own server.
As with any other API, to use it call os.loadAPI(API NAME) to use it in your own programs. The example I wrote is just that, an example. Feel free to improve it, customize it, etc.
As it is an API, I am fine with anyone using the program in any of their own programs, operating systems, etc. All I ask is that you consider including a note either in the program or on the forum post/website that credits me, especially if the program is going to be widely available or if the API plays a large part in the workings of your program. You are also allowed to redistribute the API with any of your programs/OSs, as long as it is noted somewhere that the API is not of your making.
Coming Soon
Spoiler
- Ability to get and format the current date
