Class MaxNetManager
See Also: Class MaxNet, Class MaxNetCallBack, Structure ManagerInfo, Structure ClientInfo, Structure JobsList, Structure Job, Class CJobText, Structure HSERVER, Structure JOBFRAMES, Structure JobServer, Structure ServerList, Structure WeekSchedule, Structure NetworkStatus
class MaxNetManager: public MaxNet
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
}
Methods Groups:
Construction and Destruction
Callback Methods
Session Methods
Queue Control
Client Related Methods
Job Related Methods
Server Methods
Server Group Methods
Network Archiving Functions
Construction and Destruction
The following global functions are not part of class MaxNetManager but are available for use:
Function:
MaxNetManager* CreateManager();
Remarks:
This method will create and return a new instance of the MaxNetManager class.
Function:
void DestroyManager(MaxNetManager* mgr);
Remarks:
This method will destroy an instance of the MaxNetManager class.
Parameters:
MaxNetManager* mgr
Points to the MaxNetManager object to destroy.
Methods:
Callback Methods
Prototype:
void SetCallBack(MaxNetCallBack* cb);
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.
Session Methods
Prototype:
bool FindManager(short port, char* manager, char* netmask = "255.255.255.0" );
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.
Return Value:
TRUE if a Manager is found, otherwise FALSE.
Prototype:
void Connect(short port, char* manager, bool enable_callback = false );
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.
Prototype:
void Disconnect();
Remarks:
This method will cause a disconnect from the currently connected Manager.
Prototype:
void GetManagerInfo(ManagerInfo* info);
Remarks:
This method allows basic information about the Manager to be collected.
Parameters:
ManagerInfo* info
A pointer to the Manager information.
Prototype:
bool KillManager();
Remarks:
This method will shut down the Manager and shut off the entire system.
Return Value:
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.
Prototype:
void EnableUpdate(bool enable);
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.
Queue Control
Prototype:
bool QueryManagerControl(bool wait);
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.
Return Value:
TRUE if allowed to request queue control, otherwise FALSE.
Prototype:
bool TakeManagerControl();
Remarks:
This method allows the acquisition of control of the queue.
Return Value:
TRUE if control is granted, otherwise FALSE.
Prototype:
void GrantManagerControl(bool grant);
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.
Prototype:
bool LockControl(bool lock);
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.
Return Value:
TRUE if queue control could be locked, otherwise FALSE.
Client Related Methods
Prototype:
int GetClientCount();
Remarks:
This method returns the number of clients currently connected to the Manager.
Prototype:
int ListClients(int start, int end, ClientInfo* clientList);
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.
Return Value:
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).
Job Related Methods
Prototype:
int GetJobCount();
Remarks:
This method returns the number of jobs in the queue.
Prototype:
int ListJobs(int start, int end, JobList* jobList);
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.
Return Value:
The actual number of jobs inserted in jobList. This could be either equal to the amount requested or less.
Prototype:
void GetJob(HJOB hJob, Job* job);
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.
Prototype:
void GetJob(HJOB hJob, JobList* jobList);
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.
Prototype:
void GetJobText(HJOB hJob, CJobText& jobText, int count);
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.
Prototype:
void SetJob(HJOB hJob, Job* job, CJobText& jobText, bool reset);
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.
Prototype:
int GetJobPriority(HJOB hJob);
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
Prototype:
bool SetJobPriority(HJOB hJob, int priority);
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.
Return Value:
TRUE if the priority as set successfully, otherwise FALSE
Prototype:
void SetJobOrder(HJOB* hJob, DWORD count);
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.
Prototype:
void DeleteJob(HJOB hJob);
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.
Prototype:
void SuspendJob(HJOB hJob);
Remarks:
This method will suspend a specific job. This method is the opposite of ActivateJob().
Parameters:
HJOB hJob
The job handle
Prototype:
void ActivateJob(HJOB hJob);
Remarks:
This method will activate a specific job. This method is the opposite of SuspendJob().
Parameters:
HJOB hJob
The job handle
Prototype:
int GetJobServersCount(HJOB hJob);
Remarks:
This method will return the number of Servers assigned to a given job.
Parameters:
HJOB hJob
The job handle
Prototype:
int GetJobServers(int start, int end, HJOB hJob, JobServer* servers);
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.
Return Value:
The actual number of Servers inserted in servers. This could be either equal to the amount requested or less.
Prototype:
void GetJobServerStatus(HJOB hJob, HSERVER hServer, TCHAR* status_text);
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.
TCHAR* status_text
A pointer to a string to receive the message. This string should be MAX_PATH long.
Prototype:
void SuspendJobServer(HJOB hJob, HSERVER hServer);
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.
Prototype:
void AssignJobServer(HJOB hJob, HSERVER hServer);
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.
Prototype:
int GetJobFramesCount(HJOB hJob);
Remarks:
This method will return the number of frames for a given job.
Parameters:
HJOB hJob
The job handle.
Prototype:
int GetJobFrames(int start, int end, HJOB hJob, JOBFRAMES* frames);
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.
Return Value:
The actual number of frames inserted in frames. This could be either equal to the amount requested or less.
Prototype:
int GetJobLog(int start, int count, HJOB hJob, TCHAR** buffer);
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.
TCHAR** buffer
A pointer to a TCHAR 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.
Return Value:
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.
Prototype:
bool CheckOutputVisibility(TCHAR* output, TCHAR* err);
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:
TCHAR* output
The output image file name you want to check. This is the full path and filename (i.e. d:/badpath/file.tga).
TCHAR* err
A TCHAR string to receive the error message if one exists. This will explain why the test failed (such as path not found, access denied, etc.)
Return Value:
TRUE if the Manager could write to the given path, otherwise FALSE.
Prototype:
void AssignJob(Job* job, TCHAR* archive, HSERVER* servers, CJobText& jobtext, DWORD blocksize = 0);
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.
TCHAR* 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.
Server Methods
Prototype:
int GetServerCount();
Remarks:
This method will return the number of Servers registered with the Manager.
Prototype:
int ListServers(int start, int end, ServerList* serverList);
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.
Return Value:
The actual number of Servers inserted in serverList. This could be either equal to the amount requested or less.
Prototype:
void GetServer(HSERVER hServer, ServerList* serverList);
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.
Prototype:
bool DeleteServer(HSERVER hServer);
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.
Return Value:
TRUE if the server is successfully deleted, otherwise FALSE.
Prototype:
bool ResetServerIndex(HSERVER hServer);
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.
Return Value:
TRUE if resetting the Server’s performance index was successful, otherwise FALSE.
Prototype:
void GetWeekSchedule(HSERVER hServer, WeekSchedule* schedule);
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.
Prototype:
void SetWeekSchedule(HSERVER hServer, WeekSchedule* schedule);
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.
Prototype:
void GetServerNetStat(HSERVER hServer, NetworkStatus* net_stat);
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.
Server Group Methods
Prototype:
int GetServerGroupCount();
Remarks:
This method will return the number of Server groups.
Prototype:
int GetServerGroupXCount(int group);
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.
Prototype:
int GetServerGroup(int group, int count, HSERVER* grplist, TCHAR* name);
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.
TCHAR* name
The name of the Server group. This string must be at least MAX_PATH long.
Return Value:
The number of Servers collected.
Prototype:
void NewServerGroup(int count, HSERVER* grplist, TCHAR* name);
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.
TCHAR* name
The name of the server group.
Prototype:
void DeleteServerGroup(int group);
Remarks:
This method allows you to delete a given Server group.
Parameters:
int group
The zero based index of the Server group to delete.
Network Archiving Functions
The following global functions are not part of class MaxNetManager but are available for use:
Function:
bool Maz(TCHAR* archivename, TCHAR* file_list, DWORD* filesize = 0);
Remarks:
This function creates a Network Rendering archive. This is the archive sent to the manager when submitting a new job. Note that even though you can use whatever name you feel like, the Manager and Servers will look for a "jobname.maz" file.
Parameters:
TCHAR* archivename
The full path and filename of the archive you want to create.
TCHAR* file_list
A list of NULL terminated filenames to include in the archive. You should provide a full path and filename. However, only the file names will be saved in the archive and all files are going to be un-archived in the same directory.
An example: file_list[] = {"c:\\path\\file.maz\0c:\\anotherpath\\maps.tga\0\0"};
DWORD* filesize
Optional pointer to a variable to receive the accumulated size of all files included in the archive. This is the "uncompressed" size. You can use this to compute the disk space necessary to uncompress the archive.
Return Value:
TRUE if the archive was successfully created, otherwise FALSE.
Function:
bool UnMaz(TCHAR* archivename, TCHAR* output_path);
Remarks:
This function is the opposite of Maz() and will un-archive the given archive into the specified directory.
Parameters:
TCHAR* archivename
The full path and filename of the archive you want to un-archive.
TCHAR* output_path
The path you want the files extracted to.
Return Value:
TRUE if the archive was successfully extracted, otherwise FALSE.
Function:
void jobSetJobDefaults(Job* job);
Remarks:
This function will set the default values for the given Job structure. You can use this function to prevent frequent resetting of the structure and its default fields such as size, version, etc.
Parameters:
Job *job
The job structure containing the information about the job. See the Job structure description for an explanation.
Function:
bool jobReadMAXProperties(char* filename, Job* job, CJobText& jobText);
Remarks:
This function will initialize a job structure using the data read from a specified 3ds max scene file. If you would want to submit a job based on a 3ds max file alone, you would call this function passing it to the file specified. This function takes care of filling all the fields so you can turn around and just send the job to the queue. An example of this can be found in the SDK under \MAXSDK\SAMPLES\NETRENDER\JOBASSIGN.
Parameters:
char* filename
The filename of the 3ds max scene file (*.max).
Job* job
A pointer to an empty job structure which will be initialized by the method. Because the function will initialize the structure any values present prior to calling this method will be reset.
CJobText& jobText
A reference to an empty CJobText class which will be initialized by the function. Just like the job structure, any values present prior to calling this function will be reset.
Return Value:
TRUE if reading the properties was successful, otherwise FALSE.