External Control Codes

External control codes define operations that can be performed on cluster objects. Cluster-aware applications and resource DLLs initiate external control code operations by calling control code functions.

Control code functions are general-purpose routines with multiple parameters that provide the framework for control code operations. The configuration and content of these parameters depend on the control code being used. The following pseudocode illustrates the parameters of a control code function.

Return Value = 
ControlCodeFunction
(
    Object Handle,        // for resource types, 2 parameters: cluster handle and resource type name
    Optional Node Handle, 
    Control Code,
    Input Buffer,
    Size of Input Buffer,
    Output Buffer,
    Size of Output Buffer,
    Size of the Resulting Data
);

Object Handle

For all cluster objects except resource types, this parameter will be a handle to the cluster object. For resource type, this is two parameters: a cluster handle and the resource type name.

Optional Node Handle

If you want to specify a particular node to actually perform the operation, pass a handle to that node, otherwise pass NULL.

Control Code

The control code for the operation.

Input Buffer

Pointer to a buffer containing data required for the operation, or NULL if no data is required. Refer to the control code to find out whether data is required and how the data should be formatted. You must allocate and free the memory for the buffer.

Size of Input Buffer

The size, in bytes, of the input buffer, or 0 if no input is needed.

Output Buffer

Pointer to a buffer containing data resulting from the operation, or NULL if no data is required. You must allocate a buffer and pass it to the function. If the buffer is too small to hold the data, the last parameter ("size of the resulting data" will specify the required size, allowing you to reallocate and try again. Refer to the control code to find out whether data is required and how the data should be formatted.

Size of Output Buffer

The allocated size, in bytes, of the output buffer, or 0 if no output will be generated.

Size of the Resulting Data

The control code function will specify the size of the data resulting from the operation. If the output buffer was too small to hold the data, use this value to reallocate the buffer and call the function again.

Return Value

Always a DWORD, the possible values differ from control code to control code. Refer to the control code for the values to expect.

Some control code operations require input data; others generate output data. The data can take the form of strings, arrays, or more complicated configurations such as property lists. What you pass into and expect out of a control code function is determined by the control code.

Therefore, to use a control code in a control code function, you need to know the following:

• What the control code does.
• What parameters must accompany the control code.
• What the possible return values are.

The Control Code Reference describes this information for each control code. However, there are standard patterns or configurations of parameters that result in a small set of calling conventions. For more information, see Using Control Codes.