3.3.4.1.1 Init (Opnum 7)

  • Article

The Init method is received by the server in an RPC_REQUEST packet. In response, the server initializes the object to represent the state of a Queue. The represented Queue MUST have Queue.Active set to True. If the represented Queue.Active is False, or the Pathname and FormatName input parameters cannot be resolved, this method MUST return an error without setting the ObjectIsInitialized instance variable to True. This method MUST be called prior to calling any other operation on MSMQManagement.

 HRESULT Init(
   [in, optional] VARIANT* Machine,
   [in, optional] VARIANT* Pathname,
   [in, optional] VARIANT* FormatName
 );

Machine: A pointer to a VARIANT that contains a BSTR that contains a string representation of a computer name in the DNS or NetBIOS format. If this parameter is not specified or is NULL, the server MUST ignore this parameter.

Pathname: A pointer to a VARIANT that contains a BSTR that contains a string representation of the path name describing a Queue.

FormatName: A pointer to a VARIANT that contains a BSTR that contains a string representation of the format name describing a Queue.

Return Values: The method MUST return S_OK (0x00000000) to indicate success or an implementation-specific error HRESULT on failure.

When processing this call, the server MUST follow these guidelines:

  • If the Pathname input parameter is NULL or is not specified and the FormatName input parameter is NULL or is not specified:

    • Return MQ_ERROR_INVALID_PARAMETER (0xC00E0006), and take no further action.

  • If the Pathname input parameter is not NULL and the FormatName input parameter is not NULL:

    • Return MQ_ERROR_INVALID_PARAMETER (0xC00E0006), and take no further action.

  • If the Machine input parameter is specified and is not NULL:

    • The server MUST set the ComputerName instance variable to the value of the Machine input parameter.

  • If the FormatName input parameter is specified and is not NULL and the Pathname input parameter is NULL:

    • The server MUST set the QueueFormatName instance variable to the value of the FormatName input parameter.

  • If the Pathname input parameter is specified and is not NULL, and the FormatName input parameter is NULL:

    • The server MUST generate a Get Queue Format Name From Pathname event (section 3.1.6.2) with the following inputs:

      • iPathName = the Pathname input parameter

    • If the rStatus return value is not equal to MQ_OK (0x0000000), the server MUST return an error HRESULT, and take no further action.

    • The server MUST set the QueueFormatName instance variable to the value of the FormatName return value.

  • The server MUST perform the following actions to initialize the hQmmgmtBind instance variable:

    • Create an RPC binding handle as specified in [C706] section 2, "Introduction to the RPC API".

    • The creation method MUST include:

      • If the ComputerName instance variable is not NULL:

        • The ComputerName instance variable as the server name.

      • Else:

        • The local QueueManager.ComputerName as the server name.

      • The RPC standards and transport method defined in [MS-MQMR] (sections 1.9 and 2.1).

    • If the server successfully creates the RPC binding handle:

      • The server MUST set the hQmmgmtBind instance variable to the created RPC binding handle.

    • Else:

      • The server must return an error HRESULT and take no further action.

  • The server MUST generate a QMMgmt Get Info event with the following inputs:

    • iPropID = PROPID_MGMT_QUEUE_LOCATION

    • If the rStatus return value is not equal to MQ_OK (0x00000000), the server MUST return rStatus and take no further action.

    • Else:

      • If the value of the returned rPropVar was "Remote", set the QueueIsOutgoing instance variable to True.

  • The server MUST set the ObjectIsInitialized instance variable to True.

  • Return S_OK.