IProvQueue::SubmitRequest

Submits a simple request to the Provisioning Queue Manager Service of Microsoft. Provisioning Framework (MPF).

SubmitRequest includes an option to submit a suspended request. SubmitRequest is the standard method to submit untrusted requests to queue managers for both COM and HTTP/SOAP applications.

Syntax

C++ 
HRESULT SubmitRequest  (
	BSTR bstrRequest,
	BSTR bstrNamespace,
	BSTR bstrProcedure,
	BOOL fSuspended,
	BSTR *bstrQueueID
);
Visual Basic 
Function SubmitRequest ( _
	bstrRequest As String,   _
	bstrNamespace As String, _
	bstrProcedure As String, _
	fSuspended As Boolean	_
) As String

Parameters

bstrRequest
XML data node for the request.
bstrNamespace
Name of the namespace for the procedure invoked by the request. 
bstrProcedure
Name of the procedure invoked by the request. 
fSuspended
Specifies whether the request is submitted as suspended. If set to 1 (true), the queue manager will not execute the request until you unsuspend it with a call to Activate. You can only add a child request to a parent request with IProvQueue::AddDependency if both requests are suspended.
bstrQueueID (C++) / return value (VB)
Queue ID returned for the submitted request. The queue ID returned can be used by Activate, AddDependency,  Delete, QueryResults, and QueryStatus.

Return Codes

Zero indicates success; a non-zero value represents an error. For a list of error codes, see MPF Errors.

Performance Counters

Counter Object: Microsoft Provisioning Client
Counter Instance: Queued Requests

Average Request Latency Average time for this client to execute a provisioning request. Each call to SubmitRequest contributes to the average latency of up to the last 100 requests.
Request Rate Incoming request rate for this client. Each call to SubmitRequest contributes to the average request rate of transactions per second.
Requests Executing Number of concurrently executing requests at this client. Identifies the total number of concurrent calls to SubmitRequest.
Total Requests Number of requests this client has processed. Each call to SubmitRequest increments this counter.
Total Requests Failed Total number of failed requests that this client initiated. Each call to SubmitRequest that returns a failed HRESULT increments this counter.

Remarks

Queued requests can be submitted as either activated or suspended. An activated request is always executed regardless of whether the corresponding MPF transaction succeeds or fails. A suspended request is automatically activated if the transaction succeeds; otherwise the transaction fails and is deleted. It is not possible to suspend an active request.

C++ Example

LPCWSTR wszRequest = L"<request>\n" + 
					 L"  <data>\n" +
					 L"	<organizations>\n" +
					 L"	<organization name=\"tailspintoys.com\"/>\n" +
					 L"	</organizations>\n" +
					 L"  </data>\n" +
					 L"  <context>\n" +
					 L"	<clientContext clientTransactionId=\"53367B03-63D3-44ae-B8AD-C1E57E876E6C\"/>\n" +
					 L"  </context>\n" +
					 L"</request>";

IProvQueue * pProvQueue = NULL;
BSTR bstrRequest = ::SysAllocString(wszRequest);
BSTR bstrNamespace = ::SysAllocString(L"Test Namespace");
BSTR bstrProcedure = ::SysAllocString(L"Write Request");
BSTR bstrQueueID = NULL;
HRESULT hr = E_OUTOFMEMORY;

if(bstrRequest && bstrNamespace && bstrProcedure)
{
	// Create queue manager client:
	hr = CoCreateInstance(CLSID_ProvQueueClient, NULL, CLSCTX_ALL, IID_IProvQueue, (void**)(&pProvQueue));
	if(hr == S_OK)
	{
		hr = pProvQueue->SubmitRequest(bstrRequest, bstrNamespace, bstrProcedure, FALSE, &bstrQueueID);
		pProvQueue->Release();
}
}

// Get the error description in the case of error
if(FAILED(hr))
{
	IErrorInfo* pErrInfo = NULL;
	if(::GetErrorInfo(0, &pErrInfo) == S_OK && pErrInfo)
	{
		pErrInfo->GetDescription(&bstrQueueID);
		pErrInfo->Release();
}
}

// Show the results
MessageBoxW(NULL, bstrQueueID ? bstrQueueID : L"Unknown error occured", L"Queued request results", MB_OK);

// Clean up
::SysFreeString(bstrRequest);
::SysFreeString(bstrNamespace);
::SysFreeString(bstrProcedure);
::SysFreeString(bstrQueueID);

Visual Basic Example

Dim objProvQueue
Dim strRequest
Dim strNamespace
Dim strProcedure
Dim strQueueID

On Error Resume Next

' Request:
strRequest = ""
strRequest = strRequest & "<request>"
strRequest = strRequest & "  <data>"
strRequest = strRequest & "	<organizations>"
strRequest = strRequest & "	<organization name=""tailspintoys.com""/>"
strRequest = strRequest & "	</organizations>"
strRequest = strRequest & "  </data>"
strRequest = strRequest & "  <context>"
strRequest = strRequest & "	<clientContext clientTransactionId=""53367B03-63D3-44ae-B8AD-C1E57E876E6C""/>"
strRequest = strRequest & "  </context>"
strRequest = strRequest & "</request>"

' Namespace:
strNamespace = "Test Namespace"

' Procedure:
strProcedure = "Write Request"

' Create queue manager client:
Set objProvQueue = CreateObject("Provisioning.ProvQueue.1")
If Err.Number = 0 Then
	strQueueID = objProvQueue.SubmitRequest(strRequest, strNamespace, strProcedure, False)
	If Err.Number = 0 Then
		MsgBox "Queue ID: " & strQueueID
	Else
		MsgBox Err.Description
	End If
End If

See Also

Authorization During Request Submittal, IProvQueue, SubmitTrustedRequest, XML Schema for Requests

Up Top of Page
) 1999-2002 Microsoft Corporation. All rights reserved.