PHP Documentation
From NNTPGrab
As of NNTPGrab 0.3 it is possible the create a website on which you can communicate with NNTPGrab. This is made possible by using a PHP module, which is written in the C programming language.
Installation
To enable this PHP module, you need to make sure you have the PHP development files installed on your Linux environment (mostly this is done by installing a package called php-devel). When you install NNTPGrab, the ./configure script will automatically detect your PHP installation and compile/install the PHP module. A final step is necessary before you can use the functions provided by this module. You need to open your php.ini in a editor and add the line extension=nntpgrab.so to it. It is a good idea to restart your webserver at this point.
Functions provided by the NNTPGrab PHP module
nntpgrab_connect
nntpgrab_connect - Connect to the NNTPGrab Server
mixed nntpgrab_connect(string $hostname, int $port, string $username, string $password, bool $use_ssl)
The parameters username, password and use_ssl are ignored in NNTPGrab version 0.3, but these will be used in a future version of NNTPGrab
Returns TRUE on success or a string containing an error message
Available since NNTPGrab 0.3
nntpgrab_get_is_connected
nntpgrab_get_is_connected - Retrieve the status of the connection to the NNTPGrab Server
boolean nntpgrab_get_is_connected
Returns TRUE when there is an active connection to the NNTPGrab Server
Available since NNTPGrab 0.3
nntpgrab_get_connect_errmsg
nntpgrab_get_connect_errmsg - Returns the error message belonging to the last connection attempt done by nntpgrab_connect()
string nntpgrab_get_connect_errmsg
Returns the last known error message or the message "No error occured" if the last connection attempt was successfull
Available since NNTPGrab 0.3
nntpgrab_get_version_info
nntpgrab_get_version_info - Returns several version numbers belonging to NNTPGrab
array nntpgrab_get_version_info
Returns an array with the following fields:
Array ( [glue_version] [major_version] [minor_version] [micro_version] [version] )
Available since NNTPGrab 0.3 In version 0.5, the field api_version has been renamed to glue_version
nntpgrab_config_get_avail_servers
nntpgrab_config_get_avail_servers - Retrieve a list of the available usenet servers
array nntpgrab_config_get_avail_servers()
Returns an array containing the servername's of all the available usenet server
Available since NNTPGrab 0.3
nntpgrab_config_get_server_info
nntpgrab_config_get_server_info - Retrieve the configuration details about a specific usenet server
array nntpgrab_config_get_server_info(string $servername)
When the given servername isn't known, the value NULL is returned, otherwise an array containing the following elements is returned
Array ( [servername] [hostname] [port] [username] [password] [max_threads] [priority] [use_ssl] [enabled] )
The contents of the field priority has one of the following values:
0 - High priority 1 - Normal priority 2 - Low priority
Available since NNTPGrab 0.3
nntpgrab_config_add_server
nntpgrab_config_add_server - Add a new server to the NNTPGrab configuration
boolean nntpgrab_config_add_server(array $serverconfig)
Returns TRUE when the server was successfully added to the NNTPGrab configuration or FALSE when the given servername is already known.
The serverconfig array needs to have the following fields:
Array ( [servername] [hostname] [port] [username] [password] [max_threads] [priority] [use_ssl] [enabled] )
The contents of the field priority needs to have one of the following values:
0 - High priority 1 - Normal priority 2 - Low priority
Available since NNTPGrab 0.3
nntpgrab_config_del_server
nntpgrab_config_del_server - Remove a server from the NNTPGrab configuration
boolean nntpgrab_config_del_server(string $servername)
Returns TRUE when the server was successfully removed from the NNTPGrab configuration or FALSE when the given servername isn't known.
Available since NNTPGrab 0.3
nntpgrab_config_edit_server
nntpgrab_config_edit_server - Change the settings of a server
boolean nntpgrab_config_edit_server(string $original_servername, array $serverconfig)
Returns TRUE when the change was successfully performed or FALSE when the given original_servername isn't known.
The serverconfig array needs to have the following fields:
Array ( [servername] [hostname] [port] [username] [password] [max_threads] [priority] [use_ssl] [enabled] )
The contents of the field priority needs to have one of the following values:
0 - High priority 1 - Normal priority 2 - Low priority
Available since NNTPGrab 0.3
nntpgrab_config_get_opts
nntpgrab_config_get_opts - Retrieve the basic configuration information from NNTPGrab
array nntpgrab_config_get_opts()
Returns an array containing the following fields:
Array ( [download_directory] [temp_directory] [enable_intelligent_par2_downloading] [enable_auto_import] [auto_import_directory] [move_file_after_auto_import] )
Available since NNTPGrab 0.3
The fields enable_auto_import, auto_import_directory and move_file_after_auto_import have been added in NNTPGrab 0.4
nntpgrab_config_set_opts
nntpgrab_config_set_opts - Change the basic configuration of NNTPGrab
boolean nntpgrab_config_set_opts(array $options)
Returns TRUE when the changes have been performed or FALSE when there was an error
The options array needs to have the following fields:
Array ( [download_directory] [temp_directory] [enable_intelligent_par2_downloading] [enable_auto_import] [auto_import_directory] [move_file_after_auto_import] )
Available since NNTPGrab 0.3
The fields enable_auto_import, auto_import_directory and move_file_after_auto_import have been added in NNTPGrab 0.4
nntpgrab_config_get_folder_listing
nntpgrab_config_get_folder_listing - Retrieves a list containing all the sub-folders which are in the given folder
mixed nntpgrab_config_get_folder_listing(string $parent)
Returns FALSE when the given parent isn't known by the NNTPGrab Server or an array containing all the sub-folders which are in the given folder
Available since NNTPGrab 0.3
nntpgrab_schedular_start
nntpgrab_schedular_start - Start the NNTPGrab schedular
boolean nntpgrab_schedular_start()
Returns TRUE when the schedular has been successfully started or FALSE when the schedular was already running or in a stopping state
Available since NNTPGrab 0.3
nntpgrab_schedular_stop
nntpgrab_schedular_stop - Stop the NNTPGrab schedular
nntpgrab_schedular_stop(boolean $wait)
If wait is FALSE, a request will be sent to the NNTPGrab Server to stop the schedular, but the function will not wait for the schedular to be really stopped. If wait is TRUE, this function will wait until the schedular is really stopped.
Available since NNTPGrab 0.3
nntpgrab_schedular_get_state
nntpgrab_schedular_get_state - Retrieve the current state of the NNTPGrab schedular
int nntpgrab_schedular_get_state()
This function can return one of the following values:
0 - Schedular is running 1 - Schedular is stopping 2 - Schedular is stopped
Available since NNTPGrab 0.3
nntpgrab_schedular_add_task_to_queue
nntpgrab_schedular_add_task_to_queue - Add a new task (/file) to the download queue
boolean nntpgrab_schedular_add_task_to_queue(string $collection_name, string $subject, string $poster, int $timestamp, int $file_size, array $groups, array $parts)
Returns TRUE when the task has been successfully added or FALSE when there already is a task with the same subject in the same collection_name in the download queue
The file_size needs to be in bytes
The array groups contains a list of usenet groups in which this file is published
The array parts contains an array which has the following fields:
Array
(
[0] => Array -- This block is representing one part. This block can occur multiple times
(
[message_id]
[partnum]
[size]
)
)
Available since NNTPGrab 0.3
nntpgrab_schedular_del_task_from_queue
nntpgrab_schedular_del_task_from_queue - Remove a task from the download queue
boolean nntpgrab_schedular_del_task_from_queue(string $collection_name, string $subject)
Returns TRUE when the task has been successfully removed or FALSE when the given collection_name and subject aren't known
Available since NNTPGrab 0.3
nntpgrab_schedular_restart_task
nntpgrab_schedular_restart_task - Restart a task
boolean nntpgrab_schedular_restart_task(string $collection_name, string $subject)
Returns TRUE when the task has been successfully restarted or FALSE when the given collection_name and subject aren't known
Available since NNTPGrab 0.3
nntpgrab_schedular_save_queue
nntpgrab_schedular_save_queue - Save the download queue
boolean nntpgrab_schedular_save_queue()
This function should be called after several new tasks have been added to the download queue
Returns TRUE when the save has been successfull or FALSE when there was an error
Available since NNTPGrab 0.3
nntpgrab_schedular_get_all_tasks
nntpgrab_schedular_get_all_tasks - Retrieve all the tasks in the download queue
array nntpgrab_schedular_get_all_tasks()
The array returned from this function contains a lot of data:
Array
(
[0] => Array -- This block is representing one collection. This block can occur multiple times
(
[collection_name]
[total_size]
[total_size_remaining]
[files] => Array
(
[1] => Array -- This is representing one file. This block can occur multiple times
(
[subject]
[poster]
[stamp]
[file_size]
[file_size_remaining]
[num_parts_total]
[num_parts_downloaded]
[num_parts_failed]
[status]
[groups] => Array -- This is representing a list of usenet groups in which this file is published
(
[0]
)
)
)
)
)
The fields total_size and file_size mention the size in KB (kilobytes, 1024 bytes)
Possible values for the status are:
0 - Waiting for download 1 - Downloading 2 - Waiting for decoding 3 - Decoding 4 - Finished - complete 5 - Finished - incomplete 6 - Finished - no parts available 7 - Skipped
Available since NNTPGrab 0.3
The status'es Finished - incomplete and Finished - no parts available have been added in NNTPGrab 0.4
nntpgrab_schedular_move_task
nntpgrab_schedular_move_task - Change the position and/or location of a task in the download queue
boolean nntpgrab_schedular_move_task(string $collection_name_src, string $subject_src, string $collection_name_dest, int $position_dest)
collection_name_src can be the same as collection_name_dest. If position_dest is -1, the file will be added to the end of the queue. If subject is empty, then position_dest will mean the position of all the collections in the download queue.
Available since NNTPGrab 0.3
nntpgrab_schedular_move_collection
nntpgrab_schedular_move_collection - Change the position of a collection in the download queue
boolean nntpgrab_schedular_move_collection(string $collection_name, int $new_position)
If new_position is -1, the file will be added to the end of the queue.
Available since NNTPGrab 0.3
nntpgrab_debug_get_messages
nntpgrab_debug_get_messages - Retrieve the last 100 received debug messages
array nntpgrab_debug_get_messages()
Any debug messages that the NNTPGrab Server or the Glue layer can send will be buffered in the background by the PHP module. With this function it is possible to retrieve all the debug messages which are buffered. Only the last 100 received debug messages will be kept in the buffer
Available since NNTPGrab 0.3
nntpgrab_connections_get_speed_history
nntpgrab_connections_get_speed_history - Retrieve the number of bytes received in the last 10 seconds
array nntpgrab_connections_get_speed_history()
The array returned contains the following data:
Array
(
[history] => Array
(
[0]
[1]
[2]
[3]
[4]
[5]
[6]
[7]
[8]
[9]
)
[timestamp]
[average]
)
The timestamp is an unix timestamp
Available since NNTPGrab 0.4
nntpgrab_utils_strip_subject
nntpgrab_utils_strip_subject - Split a subject in various useable fields
array nntpgrab_utils_strip_subject(string $subject)
The array returned contains the following fields:
Array ( [subject] [subject_without_partnum] [file_num] [total_files] [filename] [extension] [file_type] [par2_startnum] [num_par2_blocks] [part_num] [total_parts] )
Note that some fields can be missing. If a field is missing, it can't be detected in the given subject
Available since NNTPGrab 0.4
nntpgrab_utils_calculate_file_size
nntpgrab_utils_calculate_file_size - Returns the given file size in a human readable notation
string nntpgrab_utils_calculate_file_size(long filesize)
The filesize should be in KB (kilobytes)
Available since NNTPGrab 0.4
nntpgrab_utils_calculate_estimated_time_remaining
nntpgrab_utils_calculate_estimated_time_remaining - Make an estimation when a file with the given size will be completed
int nntpgrab_utils_calculate_estimated_time_remaining (array speed_history, int filesize)
The array speed_history should be the history part of the array returned by the function nntpgrab_connections_get_speed_history The filesize is in KB (kilobytes) The value returned is the number of seconds necessary to complete the given file size
Available since NNTPGrab 0.4
nntpgrab_utils_get_readable_time_remaining
nntpgrab_utils_get_readable_time_remaining - Returns the human readable notation of a given number of seconds
string nntpgrab_utils_get_readable_time_remaining (int time_remaining)
The value time_remaining is returned by the function nntpgrab_utils_calculate_estimated_time_remaining
Available since NNTPGrab 0.4
nntpgrab_utils_get_readable_finished_time
nntpgrab_utils_get_readable_finished_time - Returns the human readable notation of a given number of seconds relative to the current time
string nntpgrab_utils_get_readable_finished_time (int time_remaining)
The value time_remaining is returned by the function nntpgrab_utils_calculate_estimated_time_remaining
Available since NNTPGrab 0.4
