Funzione HttpCreateRequestQueue (http.h)

Articolo
11/20/2024

La funzione HttpCreateRequestQueue crea una nuova coda di richieste o apre una coda di richieste esistente.

Questa funzione sostituisce la funzione http versione 1.0 HttpCreateHttpHandle.

Sintassi

HTTPAPI_LINKAGE ULONG HttpCreateRequestQueue(
  [in]           HTTPAPI_VERSION      Version,
  [in, optional] PCWSTR               Name,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in, optional] ULONG                Flags,
  [out]          PHANDLE              RequestQueueHandle
);

Parametri

[in] Version

Struttura HTTPAPI_VERSION che indica la versione della coda delle richieste. Per la versione 2.0 dichiarare un'istanza della struttura e impostarla sul valore predefinito HTTPAPI_VERSION_2 prima di passarla a HttpCreateRequestQueue.

La versione deve essere 2.0; HttpCreateRequestQueue non supporta le code delle richieste versione 1.0.

[in, optional] Name

Nome della coda della richiesta. La lunghezza, espressa in byte, non può superare MAX_PATH.

Il parametro facoltativo name consente ad altri processi di accedere alla coda delle richieste in base al nome.

[in, optional] SecurityAttributes

Puntatore alla struttura SECURITY_ATTRIBUTES che contiene le autorizzazioni di accesso per la coda delle richieste.

Questo parametro deve essere NULL all'apertura di una coda di richieste esistente.

[in, optional] Flags

Il parametro flags definisce l'ambito della coda di richieste. Questo parametro può essere uno o più dei seguenti:

Valore	Significato
HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER	L'handle per la coda di richieste creata utilizzando questo flag non può essere usato per eseguire operazioni di I/O. Questo flag può essere impostato solo quando viene creato l'handle della coda di richieste.
HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING	Il flag HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING consente alle applicazioni di aprire una coda di richieste esistente in base al nome e recuperare l'handle della coda delle richieste. Il parametro pName deve contenere un nome di coda di richieste valido; non può essere NULL.

[out] RequestQueueHandle

Puntatore a una variabile che riceve un handle per la coda della richiesta. Questo parametro deve contenere un puntatore valido; non può essere NULL.

Valore restituito

Se la funzione ha esito positivo, restituisce NO_ERROR

Se la funzione ha esito negativo, restituisce uno dei codici di errore seguenti.

Valore	Significato
ERROR_REVISION_MISMATCH	Il parametro Version contiene una versione non valida.
ERROR_INVALID_PARAMETER	La lunghezza, in byte, del nome della coda della richiesta non può superare MAX_PATH. Il parametro pSecurityAttributes deve essere NULL quando si apre una coda di richieste esistente. Il HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER può essere impostato solo quando viene creata la coda di richieste. Il HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING può essere impostato solo quando l'applicazione dispone dell'autorizzazione per aprire una coda di richieste esistente. In questo caso, il parametro pReqQueueHandle deve essere un puntatore valido e il parametro pName deve contenere un nome di coda di richieste valido; non può essere NULL. Il parametro pReqQueueHandle restituito da HttpCreateRequestQueue è NULL.
ERROR_ALREADY_EXISTS	Il parametro pName è in conflitto con una coda di richieste esistente che contiene un nome identico.
ERROR_ACCESS_DENIED	Il processo chiamante non dispone dell'autorizzazione per aprire la coda delle richieste.
ERROR_DLL_INIT_FAILED	L'applicazione non ha chiamato HttpInitialize prima di chiamare HttpCreateRequestQueue.

Osservazioni

L'API server HTTP supporta le applicazioni esistenti che usano le code delle richieste versione 1.0, tuttavia, il nuovo sviluppo con l'API server HTTP deve usare HttpCreateRequestQueue per creare code di richieste; non usare l' HttpCreateHttpHandle. L'API versione 2.0 è compatibile solo con le code di richieste della versione 2.0 create da HttpCreateRequestQueue.

Le code di richieste HTTP versione 2 richiedono la configurazione manuale; L'applicazione deve creare i gruppi di URL e associare uno o più gruppi di URL alla coda di richieste chiamando HttpSetUrlGroupProperty con il HttpServerBindingProperty. L'applicazione configura la coda delle richieste chiamando HttpSetRequestQueueProperty con la configurazione desiderata nel parametro proprietà . Per altre informazioni sulla creazione e la configurazione di gruppi URL, vedere HttpCreateUrlGroup e HttpSetUrlGroupProperty.

Gli attributi di sicurezza possono essere forniti in pSecurityAttributes parametro solo quando viene creata la coda delle richieste. Solo l'applicazione che crea la coda delle richieste può impostare gli elenchi di controllo di accesso (ACL) nell'handle della coda delle richieste per consentire ai processi (ad eccezione dell'applicazione creatore) di aprire, ricevere richieste e inviare risposte nell'handle della coda delle richieste. Per impostazione predefinita, le applicazioni non possono aprire una coda di richieste, a meno che non siano state concesse autorizzazioni nell'ACL.

Il processo creatore può facoltativamente usare il flag HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER per indicare che non vuole ricevere richieste HTTP.

HttpCreateRequestQueue consente alle applicazioni di aprire una coda di richieste esistente con il flag HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING e recuperare l'handle nella coda delle richieste. Le applicazioni non controller possono usare questo handle per eseguire operazioni di I/O HTTP. Solo l'applicazione che crea la coda di richieste può impostare proprietà su di essa chiamando il HttpSetRequestQueueProperty.

L'handle per la coda di richieste creata da HttpCreateRequestQueue deve essere chiuso chiamando HttpCloseRequestQueue prima che l'applicazione termini o quando la sessione non è più necessaria.

Le applicazioni devono chiamare HttpInitialize prima di chiamare HttpCreateRequestQueue.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2008 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	http.h
libreria	Httpapi.lib
dll	Httpapi.dll