MQGetMachineProperties

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQGetMachineProperties function retrieves information about a queue manager computer.

HRESULT APIENTRY MQGetMachineProperties(  
  LPCWSTR lpwcsMachineName,    
  const GUID * pguidMachineID,         
  MQQMPROPS * pQMProps           
);

Parameters

lpwcsMachineName

[in] The name of the queue manager computer you want to access. Specify the NetBIOS or DNS name of the computer. If this parameter is used, set pguidMachineID to NULL.

pguidMachineID

[in] The identifier of the queue manager computer you want to access. If this parameter is used, set lpwcsMachineName to NULL.

pQMProps

[in, out] Pointer to a queue manager properties structure (MQQMPROPS) specifying which properties to retrieve.

Return Values

MQ_OK

Indicates success.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

Access to the specified computer is denied. Verify the access rights of the computer for the operation.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

Both name (lpwcsMachineName) and computer (pguidMachineID) identifiers were specified.

MQ_ERROR_ILLEGAL_MQQMPROPS (0xC00E0041)

Either pQMprops was NULL or no properties were specified.

MQ_ERROR_ILLEGAL_PROPERTY_VT (0xC00E0019)

An invalid type indicator was supplied for one of the properties specified in pQMProps.

MQ_ERROR_MACHINE_NOT_FOUND (0xC00E000D)

The specified computer could not be found in the directory service.

MQ_ERROR_NO_DS (0xC00E0013)

A connection with the directory service cannot be established. Verify permissions for accessing the directory service.

MQ_ERROR_PUBLIC_KEY_DOES_NOT_EXIST (0xC00E007A)

(Introduced in MSMQ 2.0.) This error is returned when you attempt to retrieve any encryption key property and the key is not registered in the directory service. Message Queuing was able to successfully query the directory service, but the enhanced key was not found.

MQ_ERROR_PUBLIC_KEY_NOT_FOUND. (0xC00E0079)

(Introduced in MSMQ 2.0.) This error is returned when you attempt to retrieve PROPID_QM_ENCRYPTION_KEY_PK_ENHANCED and Message Queuing is operating in a mode that supports only 40-bit encryption. For example, you are trying to retrieve the machine properties of a computer running MSMQ 1.0.

MQ_INFORMATION_DUPLICATE_PROPERTY (0x400E0005)

A duplicate property identifier was specified in pQMProps. The second entry is ignored.

MQ_INFORMATION_UNSUPPORTED_PROPERTY (0x400E0004)

An unsupported property identifier was specified in pQMProps.

Note

Apart from generic Message Queuing error codes, this function may return ADSI and LDAP error codes. For example, LDAP_BUSY (0x8007200E) is returned when the directory service server is busy.

Remarks

If lpwcsMachineName and pguidMachineID are set to NULL, the properties of the local computer are retrieved.

Valid queue manager properties are:

If a property specified by pQMProps is set to VT_NULL, Message Queuing allocates the memory needed to store the property value when MQGetMachineProperties is called. However, when the returned property type replaces the VT_NULL value, the application must still free the memory allocated for the property value by calling MQFreeMemory.

Computer properties cannot be retrieved if there is no connection to the directory service. This restriction applies to dependent client computers, independent client computers that are working offline, and Message Queuing routing servers (FRS). (For information on offline operations, see Message Queuing Offline Support.)

Equivalent COM Method

When using COM components, you can obtain the GUID of a computer from its NetBIOS or DNS name by calling the MSMQApplication.MachineIdOfMachineName method, and you can obtain the DNS or NetBIOS name of a computer from its GUID by calling the MSMQApplication.MachineNameOfMachineIdd method.

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Retrieving the computer identifier (GUID) to open a private queue	C/C++ Code Example: Opening a Private Queue Using a Computer Identifier and Queue Number
Retrieving the computer identifier (GUID) when reading messages in a dead-letter queue	C/C++ Code Example: Reading Messages in the Dead-Letter Queue C/C++ Code Example: Reading Messages in the Transactional Dead-Letter Queue

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.