Public Member Functions

MaxNetManager Class Reference

This reference page is linked to from the following overview topics: Network Rendering.


Search for all occurrences

Detailed Description

See also:
Class MaxNet, Class MaxNetCallBack, Class CJobText, Class ManagerInfo, Class ClientInfo, Class JobList, Class Job, Class HSERVER, Class JOBFRAMES, Class JobServer, Class ServerList, Class WeekSchedule, Class NetworkStatus
Description:
This class is available in release 4.0 and later only.

The MaxNetManager class provides all the methods to interact with the network rendering functions provided and acts as your primary interface. The API provided through the MaxNetManager allows clients to connect to the Network Rendering Manager and perform any and all functions available. It encapsulates all the networking details leaving the client code to concentrate on whatever it needs to do. The API handles all networking code and the intricacies of the communication protocols used by the lower layers. This class is derived from the MaxNet class which is solely used for exception handling as shown below.

Sample Code:
try {

// the code being tried

} catch (MaxNet* maxerr) {

// handle the error

// do NOT delete maxerr

// use maxerr->GetErrorText() to get the error description

// use maxerr->GetError() to get the error code

}
Method Groups:
See Method Groups for Class MaxNetManager.

#include <maxnet_manager.h>

Inheritance diagram for MaxNetManager:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual  ~MaxNetManager ()
virtual void  SetCallBack (MaxNetCallBack *cb)=0
virtual bool  FindManager (short port, char *manager, char *netmask="255.255.255.0")=0
virtual void  Connect (short port, char *manager=NULL, bool enable_callback=false)=0
virtual void  Disconnect ()=0
virtual void  GetManagerInfo (ManagerInfo *info)=0
virtual bool  KillManager ()=0
virtual void  EnableUpdate (bool enable=true)=0
virtual bool  QueryManagerControl (bool wait)=0
virtual bool  TakeManagerControl ()=0
virtual void  GrantManagerControl (bool grant)=0
virtual bool  LockControl (bool lock)=0
virtual int  GetClientCount ()=0
virtual int  ListClients (int start, int end, ClientInfo *clientList)=0
virtual int  GetJobCount ()=0
virtual int  ListJobs (int start, int end, JobList *jobList)=0
virtual void  GetJob (HJOB hJob, JobList *jobList)=0
virtual void  GetJob (HJOB hJob, Job *job)=0
virtual void  GetJobText (HJOB hJob, CJobText &jobText, int count)=0
virtual void  SetJob (HJOB hJob, Job *job, CJobText &jobText, bool reset)=0
virtual int  GetJobPriority (HJOB hJob)=0
virtual bool  SetJobPriority (HJOB hJob, int priority)=0
virtual void  SetJobOrder (HJOB *hJob, DWORD count)=0
virtual void  DeleteJob (HJOB hJob)=0
virtual void  SuspendJob (HJOB hJob)=0
virtual void  ActivateJob (HJOB hJob)=0
virtual int  GetJobServersCount (HJOB hJob)=0
virtual int  GetJobServers (int start, int end, HJOB hJob, JobServer *servers)=0
virtual void  GetJobServerStatus (HJOB hJob, HSERVER hServer, MCHAR *status_text)=0
virtual void  SuspendJobServer (HJOB hJob, HSERVER hServer)=0
virtual void  AssignJobServer (HJOB hJob, HSERVER hServer)=0
virtual int  GetJobFramesCount (HJOB hJob)=0
virtual int  GetJobFrames (int start, int end, HJOB hJob, JOBFRAMES *frames)=0
virtual int  GetJobLog (int start, int count, HJOB hJob, MCHAR **buffer)=0
virtual bool  CheckOutputVisibility (MCHAR *output, MCHAR *err)=0
virtual void  AssignJob (Job *job, MCHAR *archive, HSERVER *servers, CJobText &jobtext, DWORD blocksize=0)=0
virtual int  GetServerCount ()=0
virtual int  ListServers (int start, int end, ServerList *serverList)=0
virtual void  GetServer (HSERVER hServer, ServerList *serverList)=0
virtual bool  DeleteServer (HSERVER hServer)=0
virtual bool  ResetServerIndex (HSERVER hServer)=0
virtual void  GetWeekSchedule (HSERVER hServer, WeekSchedule *schedule)=0
virtual void  SetWeekSchedule (HSERVER hServer, WeekSchedule *schedule)=0
virtual void  GetServerNetStat (HSERVER hServer, NetworkStatus *net_stat)=0
virtual int  GetServerGroupCount ()=0
virtual int  GetServerGroupXCount (int group)=0
virtual int  GetServerGroup (int group, int count, HSERVER *grplist, MCHAR *name)=0
virtual void  NewServerGroup (int count, HSERVER *grplist, MCHAR *name)=0
virtual void  DeleteServerGroup (int group)=0

Constructor & Destructor Documentation

virtual ~MaxNetManager ( ) [inline, virtual]
Remarks:
Destructor.
{;}

Member Function Documentation

virtual void SetCallBack ( MaxNetCallBack cb ) [pure virtual]
Remarks:
Sets a callback method to receive information updates about various asynchronous events from the MaxNet API. It is not required to set up this callback.
Parameters:
MaxNetCallBack* mgr

Points to a MaxNetCallBack object.
virtual bool FindManager ( short  port,
char *  manager,
char *  netmask = "255.255.255.0" 
) [pure virtual]
Remarks:
This method will broadcast a message to the local area network in order to look for a Manager. If a Manager is found, the method returns its name in manager.
Parameters:
short port

Specifies which port will be used to access the Manager. Unless there is a specific reason to use a particular port, use the default DF_MGRPORT.

char* manager

A string representing the name of the Manager will be put into this variable. The variable itself should be MAX_PATH in size.

char* netmask

Specifies which local area network mask should be used for the scope of the broadcast. The default of 255.255.255.0 should work for most networks that are not divided into subnets.
Returns:
true if a Manager is found, otherwise false.
virtual void Connect ( short  port,
char *  manager = NULL,
bool  enable_callback = false 
) [pure virtual]
Remarks:
This method allows you to connect to a Network Rendering Manager.
Parameters:
short port

Specifies which port will be used to access the Manager. Unless there is a specific reason to use a particular port, use the default DF_MGRPORT.

char* manager

A string representing the name or IP number of the Manager you want to connect to. The network name requires the network to have some form of name to address translation. It is recommended to use the name provided by MaxNetManager::FindManager().

bool enable_callback = false

This parameter enables or disables asynchronous messages from the Manager. If you connect to the Manager in order to collect information about the network queue then it is recommended to enable (set to true) this parameter in order to keep your lists updated. Otherwise you have to poll the Manager at various times to check for changes. When enabled calls will be received though the MaxNetCallBack mechanism informing you whenever a new job has been completed, an error has occurred, a Server has changed, etc.
virtual void Disconnect ( ) [pure virtual]
Remarks:
This method will cause a disconnect from the currently connected Manager.
virtual void GetManagerInfo ( ManagerInfo info ) [pure virtual]
Remarks:
This method allows basic information about the Manager to be collected.
Parameters:
ManagerInfo* info

A pointer to the Manager information.
virtual bool KillManager ( ) [pure virtual]
Remarks:
This method will shut down the Manager and shut off the entire system.
Returns:
TRUE if successful, otherwise FALSE. A reason for failure might be because this method is called without having the proper Manager rights such as operating in read only mode. Further explanation can be found in the TakeManagerControl() method.
virtual void EnableUpdate ( bool  enable = true ) [pure virtual]
Remarks:
This method toggles updates from the Manager. For this method to function you will need to enable the enable_callback in MaxNetManager::Connect(). The use of this method allows you to temporarily disable updates from the Manager which might be useful in a situation when you are submitting many jobs at once or executing any other large number of changes. Instead of receiving updates for all changes, you would temporarily disable the callbacks so you could execute your many changes and when done, re-enable the callbacks.
Parameters:
bool enable

TRUE or FALSE to enable or disable, respectively.
virtual bool QueryManagerControl ( bool  wait ) [pure virtual]
Remarks:
This method queries the Manager to check if you can take control of the queue. If no one has the queue control, it will immediately return true. If someone else has control, the Manager will ask the controlling client if it wants to relinquish control. If relinquished, the method returns true, if control is not relinquished the method will return false.
Parameters:
bool wait

This parameter can be set to true in order to wait for an answer in case someone has control over the queue, causing this method not to return until it receives an answer from the controlling client. If there is no response from the controlling client, the method will time out in 10 seconds after which it will return true to allow a request for queue control.
Returns:
TRUE if allowed to request queue control, otherwise FALSE.
virtual bool TakeManagerControl ( ) [pure virtual]
Remarks:
This method allows the acquisition of control of the queue.
Returns:
TRUE if control is granted, otherwise FALSE.
virtual void GrantManagerControl ( bool  grant ) [pure virtual]
Remarks:
This method allows you to issue a grant or deny response to a MaxNetCallBack message. If you are the controlling client while another client wants control of the queue by calling the QueryManagerControl() method you will receive a message through the MaxNetCallBack mechanism. If you do not respond, control will be taken away from you automatically after 10 seconds and granted to the requesting client.
Parameters:
bool grant

This parameter allows you to respond TRUE to relinquish control of the queue or FALSE if you do not want to relinquish control.
virtual bool LockControl ( bool  lock ) [pure virtual]
Remarks:
This method allows you to temporarily lock the queue control when performing a series of changes and don't want to get interrupted. While the queue control is locked, no queries are made. They all return false to prevent anyone from taking control of the queue. This method can only be called if you already have queue control. Please, do not forget to unlock the queue control after you are done performing your changes.
Parameters:
bool lock

Set this parameter to TRUE if you want to lock the queue or FALSE if you want to unlock the queue.
Returns:
TRUE if queue control could be locked, otherwise FALSE.
virtual int GetClientCount ( ) [pure virtual]
Remarks:
This method returns the number of clients currently connected to the Manager.
virtual int ListClients ( int  start,
int  end,
ClientInfo clientList 
) [pure virtual]
Remarks:
This method allows you to list all the clients currently connected to the Manager.
Parameters:
int start

The first client in the list to return.

int end

The last client in the list to return. If you want the entire list of clients at once set the start and end to 0 and -1, respectively.

ClientInfo* clientList

The array to receive the list of clients. This array should be large enough to receive the number of clients requested.
Returns:
The actual number of clients inserted in clientList. This could be either equal to the amount requested or less (if some client disconnected from the Manager).
virtual int GetJobCount ( ) [pure virtual]
Remarks:
This method returns the number of jobs in the queue.
virtual int ListJobs ( int  start,
int  end,
JobList jobList 
) [pure virtual]
Remarks:
This method allows you to list all the jobs in the queue.
Parameters:
int start

The first job in the list to return.

int end

The last job in the list to return. If you want the entire list of jobs at once set the start and end to 0 and -1, respectively.

JobList* jobList

The array to receive the list of jobs. This array should be large enough to receive the number of jobs requested.
Returns:
The actual number of jobs inserted in jobList. This could be either equal to the amount requested or less.
virtual void GetJob ( HJOB  hJob,
JobList jobList 
) [pure virtual]
Remarks:
This method allows you to get a single record for the jobList given the specified job handle.
Parameters:
HJOB hJob

The job handle.

JobList* jobList

A pointer to a JobList structure for the received job.
virtual void GetJob ( HJOB  hJob,
Job job 
) [pure virtual]
Remarks:
This method allows you to get an individual job description structure.
Parameters:
HJOB hJob

The job handle.

Job* job

A pointer to a Job structure for the received job.
virtual void GetJobText ( HJOB  hJob,
CJobText jobText,
int  count 
) [pure virtual]
Remarks:
Use this method to request the CJobText for a particular job. (See the CJobText class description for an explanation). Some job information are random both in number as they are in size. The job description structure (Job) will only show static elements. In order to get dynamic elements or elements with variable length, the CJobText class is used.
Parameters:
HJOB hJob

The job handle.

CjobText& jobText

A reference to a CJobText class to receive the information.

int count

The number of elements you are interested in receiving. The number of elements can be found in Job.jobtextcount.
virtual void SetJob ( HJOB  hJob,
Job job,
CJobText jobText,
bool  reset 
) [pure virtual]
Remarks:
This method submits changes to an existing job. Once you collect a job, you can change settings in both the Job structure as in the CJobText elements and send it back so the changes can be applied.

Note that you must use a Getjob() and SetJob() combination in order to make sure all the elements are correct. The Manager will automatically complete some of the structure members. It is not possible to create a new structure, fill in the data, and submit it. You can only do that when submitting a new job, which is then handled by a different set of methods.
Parameters:
HJOB hJob

The job handle.

Job* job

A pointer to the job description.

CJobText& jobText

A reference to a CJobText class with the description of elements.

bool reset

This flag indicates whether or not the job is started from scratch. If set to FALSE it will continue from the current stage.
virtual int GetJobPriority ( HJOB  hJob ) [pure virtual]
Remarks:
This method returns the job priority value for the specified Job.
Parameters:
HJOB hJob

The handle to the job for which to obtain its priority
virtual bool SetJobPriority ( HJOB  hJob,
int  priority 
) [pure virtual]
Remarks:
This method allows you to set the priority of a specified job.
Parameters:
HJOB hJob

The handle to the job for which to obtain its priority

int priority

The priority value you want to assign to the job.
Returns:
TRUE if the priority as set successfully, otherwise FALSE
virtual void SetJobOrder ( HJOB *  hJob,
DWORD  count 
) [pure virtual]
Remarks:
This method allows you to set the job order for a specific job.
Parameters:
HJOB hJob

The handle to the job for which to obtain its priority

DWORD count

The job order index.
virtual void DeleteJob ( HJOB  hJob ) [pure virtual]
Remarks:
This method will delete a job from the queue permanently and remove all files related to the job.
Parameters:
HJOB hJob

The job handle.
virtual void SuspendJob ( HJOB  hJob ) [pure virtual]
Remarks:
This method will suspend a specific job. This method is the opposite of ActivateJob().
Parameters:
HJOB hJob

The job handle
virtual void ActivateJob ( HJOB  hJob ) [pure virtual]
Remarks:
This method will activate a specific job. This method is the opposite of SuspendJob().
Parameters:
HJOB hJob

The job handle
virtual int GetJobServersCount ( HJOB  hJob ) [pure virtual]
Remarks:
This method will return the number of Servers assigned to a given job.
Parameters:
HJOB hJob

The job handle
virtual int GetJobServers ( int  start,
int  end,
HJOB  hJob,
JobServer servers 
) [pure virtual]
Remarks:
This method will return a list of the Servers assigned to a given job.
Parameters:
int start

The first Server in the list to return.

int end

The last Server in the list to return. If you want the entire list of servers at once set the start and end to 0 and -1, respectively.

HJOB hJob

The job handle.

JobServer* servers

The array to receive the list of Servers. This array should be large enough to receive the number of Servers requested.
Returns:
The actual number of Servers inserted in servers. This could be either equal to the amount requested or less.
virtual void GetJobServerStatus ( HJOB  hJob,
HSERVER  hServer,
MCHAR *  status_text 
) [pure virtual]
Remarks:
This method allows you to obtain the textual status of a specific Server for a given job. The JobServer structure return by GetJobServers() will only describe the status of a Server using a flag. If the flag shows the Server status is "Error", you can use this method to receive a more descriptive text message, like "Could not write to d:/path/file.tga".
Parameters:
HJOB hJob

The job handle.

HSERVER hServer

The Server handle.

MCHAR* status_text

A pointer to a string to receive the message. This string should be MAX_PATH long.
virtual void SuspendJobServer ( HJOB  hJob,
HSERVER  hServer 
) [pure virtual]
Remarks:
This method will suspend a specific Server for a given job. The Server will stop working with the given job and start working on another one, provided another job exists. Use the AssignJobServer() to reactive it.
Parameters:
HJOB hJob

The job handle.

HSERVER hServer

The Server handle.
virtual void AssignJobServer ( HJOB  hJob,
HSERVER  hServer 
) [pure virtual]
Remarks:
This method can be used to assign a Server to a given job.
Parameters:
HJOB hJob

The job handle.

HSERVER hServer

The Server handle.
virtual int GetJobFramesCount ( HJOB  hJob ) [pure virtual]
Remarks:
This method will return the number of frames for a given job.
Parameters:
HJOB hJob

The job handle.
virtual int GetJobFrames ( int  start,
int  end,
HJOB  hJob,
JOBFRAMES frames 
) [pure virtual]
Remarks:
This method will return a list of frames for a given job.
Parameters:
int start

The first frame in the list to return.

int end

The last frame in the list to return. If you want the entire list of frames at once set the start and end to 0 and -1, respectively.

HJOB hJob

The job handle.

JOBFRAMES* frames

The array to receive the list of frames with information for each individual frame. This array should be large enough to receive the number of frames requested.
Returns:
The actual number of frames inserted in frames. This could be either equal to the amount requested or less.
virtual int GetJobLog ( int  start,
int  count,
HJOB  hJob,
MCHAR **  buffer 
) [pure virtual]
Remarks:
This method will return the log file for a given job.
Parameters:
int start

The first log file line to return (base zero, 0 is the first line).

int count

The number of lines (rows) to return. If you want the whole file at once, set start to 0 and count to -1. Alternatively, if you want any lines added since the last time you call, set start to the last line you collected + 1 and count to -1.

HJOB hJob

The job handle.

MCHAR** buffer

A pointer to a MCHAR array to receive the lines of the log file. The buffer will be allocated so it will accommodate the incoming data. This array should be freed using LocalFree() when you are finished.
Returns:
The size of the allocated buffer. This is the size of the entire buffer including the last NULL terminating byte. If GetJobLog() returns 0, it means there are no new log file lines available.
virtual bool CheckOutputVisibility ( MCHAR *  output,
MCHAR *  err 
) [pure virtual]
Remarks:
When submitting a job, you can use this method to find out if the Manager can write a given output image file. This is usually the case when you have the output image file set to a local drive. The other participants in the network rendering may not be able to "see" this path and they will eventually fail. This test is not guaranteed as the Servers may have a different set of rights than the Manager, in which case the Manager might fail the write test while the Servers would have no problem otherwise.
Parameters:
MCHAR* output

The output image file name you want to check. This is the full path and filename (i.e. d:/badpath/file.tga).

MCHAR* err

A MCHAR string to receive the error message if one exists. This will explain why the test failed (such as path not found, access denied, etc.)
Returns:
TRUE if the Manager could write to the given path, otherwise FALSE.
virtual void AssignJob ( Job job,
MCHAR *  archive,
HSERVER servers,
CJobText jobtext,
DWORD  blocksize = 0 
) [pure virtual]
Remarks:
This method allows you to assign a new job to the network queue.
Parameters:
Job* job

The job structure containing the information about the job. See the Job structure description for an explanation.

MCHAR* archive

The full path and filename of the archive containing the job files. This is the "*.maz" file created by the Maz() function in the API.

HSERVER* servers

An array containing the Servers assigned to this job. If the job flag is set to "use all Servers" and job.servercount is zero, this argument can be NULL (ignored). Otherwise it should be an array job.servercount * sizeof(HSERVERS) long with the list of Servers to assign to this job.

CJobText& jobtext

A reference to a CJobText class with the proper elements.

DWORD blocksize

An optional alternate block size to use for network transfers. If blocksize is set to zero, the API will use the default DF_READCHUNK. You may want to set this to something smaller if you are running over slow connections such as a modem connection. You may want to make it larger if you have a high performance network. This number will determine how large of a block of data to send at once to the Manager.
virtual int GetServerCount ( ) [pure virtual]
Remarks:
This method will return the number of Servers registered with the Manager.
virtual int ListServers ( int  start,
int  end,
ServerList serverList 
) [pure virtual]
Remarks:
This method allow you to list the Servers registered with the Manager.
Parameters:
int start

The first Server to return.

int end

The last Server to return. If you want the whole list at once, set start to 0 and end to -1.

ServerList* serverList

The array to receive the list of Servers. This array should be large enough to receive the number of Servers requested.
Returns:
The actual number of Servers inserted in serverList. This could be either equal to the amount requested or less.
virtual void GetServer ( HSERVER  hServer,
ServerList serverList 
) [pure virtual]
Remarks:
This method allows you to get a Server and retrieve a single record in the serverList given

the Server handle.
Parameters:
HSERVER hServer

The handle to the Server.

ServerList* serverList

A pointer to the ServerList in which to retrieve the Server.
virtual bool DeleteServer ( HSERVER  hServer ) [pure virtual]
Remarks:
This method allows you to delete a Server from the Manager's Server list. You can not delete an active Server (i.e. a Server which is currently working on a job).
Parameters:
HSERVER* hServer

The Server handle.
Returns:
TRUE if the server is successfully deleted, otherwise FALSE.
virtual bool ResetServerIndex ( HSERVER  hServer ) [pure virtual]
Remarks:
The Manager keeps a performance index for each Server. This index is computed based on the Server performance while rendering frames. All factors are taken into consideration such as the time it takes to load a job, the time it takes to process requests, the time it takes to render a frame, the memory and CPU load, etc. This index is in turn used internally to determine the best distribution of workload. You can use this method to reset a Server's performance index.
Parameters:
HSERVER* hServer

The Server handle.
Returns:
TRUE if resetting the Server's performance index was successful, otherwise FALSE.
virtual void GetWeekSchedule ( HSERVER  hServer,
WeekSchedule schedule 
) [pure virtual]
Remarks:
This method allows you to obtain a given Server's weekly schedule structure.
Parameters:
HSERVER* hServer

The Server handle.

WeekSchedule* schedule

A pointer to a WeekSchedule structure to receive the schedule.
virtual void SetWeekSchedule ( HSERVER  hServer,
WeekSchedule schedule 
) [pure virtual]
Remarks:
This method allows you to set a given Server's weekly schedule structure.
Parameters:
HSERVER* hServer

The Server handle.

WeekSchedule* schedule

A pointer to a WeekSchedule structure with the new weekly schedule.
virtual void GetServerNetStat ( HSERVER  hServer,
NetworkStatus net_stat 
) [pure virtual]
Remarks:
This method allows you to obtain the network status for a given server. This method mostly serves as means to check network diagnostics.
Parameters:
HSERVER* hServer

The Server handle.

NetworkStatus* net_stat

A pointer to a NetworkStatus structure to receive the status data.
virtual int GetServerGroupCount ( ) [pure virtual]
Remarks:
This method will return the number of Server groups.
virtual int GetServerGroupXCount ( int  group ) [pure virtual]
Remarks:
This method will return the number of Servers for a given Server group.
Parameters:
int group

The zero based index into the Server group list.
virtual int GetServerGroup ( int  group,
int  count,
HSERVER grplist,
MCHAR *  name 
) [pure virtual]
Remarks:
This method allows you to obtain a Server group.
Parameters:
int group

The zero based index into the Server group list.

int count

The number of Servers to send, in order to define the size of the grplist.

HSERVER* grplist

The array in which the list of Servers will be returned. This array should be large enough to accommodate count Servers.

MCHAR* name

The name of the Server group. This string must be at least MAX_PATH long.
Returns:
The number of Servers collected.
virtual void NewServerGroup ( int  count,
HSERVER grplist,
MCHAR *  name 
) [pure virtual]
Remarks:
This method allows you to submit (create) a new Server group.
Parameters:
int count

The number of Servers in the list.

HSERVER* grplist

The array containing count Servers.

MCHAR* name

The name of the server group.
virtual void DeleteServerGroup ( int  group ) [pure virtual]
Remarks:
This method allows you to delete a given Server group.
Parameters:
int group

The zero based index of the Server group to delete.

MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager
MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager MaxNetManager