sheepit-shadow-nabber/protocol.txt

=== Session creation ===

Url: Server url
Parameters as GET:
    * login: User's login in plain text.
    * password: User's password in plain text.
    * version: Client's version, for example 3.3.1762.
    * os: Computer's operating system, at the moment only "windows", "mac" and "linux" are supported.
    * bits: Architecture size, at the moment only "32bit" and "64bit" are supported.
    * cpu_family: CPU's family, on linux it can be get in /proc/cpuinfo via the attribute "cpu family".
    * cpu_model: CPU's model, on linux it can be get in /proc/cpuinfo via the attribute "model".
    * cpu_model_name: CPU's model as human readable, on linux it can be get in /proc/cpuinfo via the attribute "model name".
    * cpu_cores: Number of core (or thread) available.
    * ram: Memory available in kilo bytes.
    * extras (optional): Extra data use for the configuration.
    * hostname (optional): Hostname of the machine, it's useful when the user have multiple machines with same hardware configuration. It's only used for display for server website.

Answer in case of error:
<?xml version="1.0" encoding="utf-8" ?>
<config status="X" />
where X:
    * 100 => Error no version given.
    * 101 => Client is too old.
    * 102 => Authentication failure.
    * 103 => WebSession have expired.
    * 104 => Missing parameter.
    * something else => Unknown error.

Answer with no error:
The status="0" to specify everything is okay, plus a list of destination for request, validation job, etc.
It provide a destination for error, job request, job validation, download needed file, heart beat (keepmealive), logout, thumbnail of last frame rendered and how many credits was earned so far.
The maximum duration between two heart beat is given by the attribute "max-period" who is in second.
<?xml version="1.0" encoding="utf-8" ?>
<config status="0">
    <request type="validate-job" path="/server/send_frame.php" />
    <request type="request-job" path="/server/request_job.php" />
    <request type="download-archive" path="/server/download.php" />
    <request type="error" path="/server/error.php" />
    <request type="keepmealive" path="/server/keepmealive.php" max-period="1440" />
    <request type="logout" path="/account.php?mode=logout&worker=1" />
    <request type="last-render-frame" path="/ajax.php?action=webclient_get_last_render_frame_ui&type=raw"/>
    <request type="credits-earned" path="/ajax.php?action=credits_earned_on_session"/>
</config>


=== Session end ===

Url: use the request type "logout" from the configuration answer.
No additional parameter is required.

=== Download renderer archive ===

Url: use the request type "download-archive" from the configuration answer.
Parameter as GET or POST:
    * type: "binary"
    * job: id of the job

Answer:
No error: the file
On error: an 404 http code


=== Download job archive ===

Url: use the request type "download-archive" from the configuration answer.
Parameter as GET or POST:
    * type: "job"
    * job: Id of the job

Answer:
No error: the file
On error: an 404 http code


=== Job request ===

Url: use the request type "request-job" from the configuration answer.
Parameter as GET or POST:
    * computemethod: What are my computer capability, 0 for using gpu and cpu (the computer is capable of using both but it will not use it at the same time), 1 for cpu only, 2 for gpu only. 
    * cpu_cores: Number of cores currently available for rendering (optional).
    * gpu_model: Model name of the GPU available for rendering
    * gpu_ram: GPU's memory (in byte)

Answer in case of error:
<?xml version="1.0" encoding="utf-8" ?>
<jobrequest status="X" />
where X:
    * 0   => No error
    * 200 => No job available, the client should wait few minutes before requesting a new job (typical value is 1hour).
    * 201 => The client does not have rendering right.
    * 202 => Client's session is dead. Client should do a config request before requesting a new job.
    * 203 => Client's session have been disabled (usually because the client is sending broken frame). The client warms the end user and logout.
    * 205 => No renderer is available for Client's hardware (pair of OS and architecture). For example Blender is not available for MacOS 32bits.
    * 206 => Server is in maintenance mode, it will not give frame to do (but it will keep the session alive).
    * 207 => Server is too busy to run the scheduler, it will not give frame to do (but it will keep the session alive).
    * something else => unknown error
    
Answer with no error:
<?xml version="1.0" encoding="utf-8" ?>
<jobrequest status="0">
    <frames remaining="1187" />
    <job id="1" use_gpu="1" archive_md5="11d046f9912267a29f99a731c7e4e3b0" path="compute_method.blend" frame="0340" synchronous_upload="1" name="human name" password="some_passowrd">
        <renderer md5="ceda00890578762c6fac96f1a13f671a" commandline=".e --factory-startup --disable-autoexec -b .c -o .o -f .f -x 1" update_method="remainingtime"/>
        <script>import bpy
# disable the GPU for Cycles
bpy.context.user_preferences.system.compute_device_type = "NONE"

# if it's a movie clip, switch to png
fileformat = bpy.context.scene.render.image_settings.file_format
if fileformat != 'BMP' and fileformat != 'PNG' and fileformat != 'JPEG' and fileformat != 'TARGA' and fileformat != 'TARGA_RAW' :
    bpy.context.scene.render.image_settings.file_format = 'PNG'
    #bpy.context.scene.render.file_extension = '.png'
    bpy.context.scene.render.filepath = ''

        </script>
    </job>
</jobrequest>



=== Job validation ===

Url: use the request type "validate-job" from the configuration answer.
Parameter as GET or POST:
    * job: Job's id
    * frame: Job's frame number
    * rendertime: Job's render time
    * extras: Job's extra data
    * file: Frame to validate as form-data post
    * memoryused (optional): Max memory used for the render
    * cores (optional): Number of cores used from the render
Parameter as form-urlencoded:
    * file: the frame to send   

Answer in case of error:
<jobvalidate status="X" />
where X:
    * 0 => No error
    * 300 => Missing parameter in request.
    * 301 => Client generated a broken frame (usually an too old gpu who generated black frame).
    * 302 => Client sent a file who is not an image.
    * 303 => Failed to upload the image to the server.
    * 304 => Client's session is disabled or dead.
    * something else => unknown error

=== Session heart bit ===

Url: use the request type "keepmealive" from the configuration answer.
Parameter as GET or POST:
    * job: Id of the rendering job
    * frame: Frame number of the rendering job
    * extras: Extras data get on job request of the rendering job
    * rendertime: current render time (optional)
    * remainingtime: current remaining time to render the frame (optional)

Answer:
<?xml version="1.0" encoding="utf-8" ?>
<keepmealive status="X" />
where X:
    * 0 => No error.
    * 400 => Stop this job (usually because the job has be cancelled on the server side).

=== Error send ===

Url: use the request type "error" from the configuration answer.
Parameter as GET or POST:
    * job: job's id
    * frame: job's frame number
    * extras: job's extra data
    * rendertime (optional): job's frame number
    * memoryused (optional): max memory used for the render (in kilo bytes)
Parameter as form-urlencoded:
    * file: the error log to send   


Answer:
<?xml version="1.0" encoding="utf-8" ?>
<error status="X" />
where X:
    * 0 => No error