INFOPA.net » INFOPedia Wiki

Piccola Guida alle API Windows

(Quello che serve per il corso)

Le informazioni contenute in questa pagina provengono dal sito di MSDN condite da sperimentazioni personali e costituiscono una libera espressione di opinioni personali. Se vi sembrano striminzite, bene! Quello che volevo fare era proprio andare all'essenziale. Per maggiori informazioni va benissimo MSDN. Se credete di trovare errori ditelo pure, ne discuteremo insieme.

Qualche "dritta" per leggere i prototipi.

Una rapida nota sulle convenzioni osservate per alcuni tipi di dati e nomi di variabili. Le API Win32 usano la cosiddetta "Notazione Ungherese" per la denominazione delle variabili. Questa notazione richiede che il nome della variabile sia preceduto da un prefisso che ne indica il tipo, in modo tale da rendere immediata la comprensione del codice.

I tipi di windows

Oltre ai tipi ANSI su Windows vengono definiti molti altri tipi di dato, molto usati nella libreria di sistema, quindi é bene saperli usare.

Tipi interi senza segno

BYTE 8 bit (0 - 255)
WORD 16 bit (0 - 65535)
DWORD 32 bit (0 - 4294967295)
DWORDLONG 64 bit (0 - 18446744073709551615)

HANDLE - identificativo di una risorsa (Thread, Mutex o quant'altro...). E' un intero, ma fate finta di non saperlo. Non fate aritmetica con variabili di questo tipo, davvero.

Puntatori

P<tipo>, LP<tipo>: Puntatore a <tipo> [32 bit] (es. LPWORD, LPCHAR, LPVOID). La differenza tra P ed LP aveva senso nei sistemi a 16 bit (win 3.1). Adesso sono la stessa cosa. Usate LP.

Gestione dei Thread (si legge thréd, con la "e", non thrid con la "i")

CreateThread

Crea un nuovo thread.

Restituisce un HANDLE al nuovo thread. Conservatelo con cura: tutte le chiamate di sistema che manipolano i thread necessitano di questo valore. In ogni funzione troverete sempre un parametro HANDLE hThread, che vuol dire sempre la stessa cosa: su quale thread deve operare la funzione che state invocando.

HANDLE CreateThread(
LPSECURITY_ATTRIBUTES lpThreadAttributes,
SIZE_T dwStackSize,
LPTHREAD_START_ROUTINE lpStartAddress,
LPVOID lpParameter,
DWORD dwCreationFlags,
LPDWORD lpThreadId
);

lpThreadAttributes

puntatore a una struttura di descrittori di sicurezza. Fondamentamentalmente a noi non serve. (NULL)

dwStackSize

dimensione iniziale dello stack. Usate 0 per il default.

lpstartAddress

la funzione che deve girare nel Thread separato. Questa va dichiarata "DWORD my_func( LPVOID param )", param riceve il valore lpParameter (vedi sotto)

lpParameter

puntatore ai dati passati all funzione nel nuovo thread

dwCreationFlag

FLAG di creazione del thread
+ SUSPENDED, il thread non si avvia automaticamente dopo la creazione (vedi ResumeThread, SuspendThread)

0 default

lpThreadId

Sostanzialmente inutile (NULL)

/* (NdM - Nota di MarKuS)
se create più di un thread, ad es. in un ciclo, ricordatevi che __non__ potete
fare affidamento sull'ordine di esecuzione dei diversi thread. */

HANDLE hThreads[N_THREADS];
for (i=0;i<N_THREADS; i++) {
hThreads[i] = CreateThread( NULL, 0, my_func, &i, 0, NULL ); /* NO! */
}

/* i verrà modificato mille volte prima che il primo dei thread creati si svegli ! */

ResumeThread

Decrementa il numero di sospensioni del thread. Quando il numero di sospensioni è zero, il thread riprende

DWORD WINAPI ResumeThread(
HANDLE hThread
);

SuspendThread

Sospende il thread (aumenta il numero di sospensioni se il thread è già sospeso)

DWORD WINAPI SuspendThread(
HANDLE hThread
);

TerminateThread

Uccide un thread senza pietà. Non c'è motivo di usarla.
«TerminateThread è una funzione pericolosa da utilizzare solo nei casi più estremi.» (MSDN)

BOOL WINAPI TerminateThread(
HANDLE hThread,
DWORD dwExitCode
);

dwExitCode

Codice di ritorno del Thread terminato

Mutex & Semafori

CreateMutex

Crea un oggetto mutex, o vi accede.

ReleaseMutex

Rilascia un mutex(up).

BOOL WINAPI ReleaseMutex(
HANDLE hMutex
);

CreateSemaphore

Crea un oggetto semaforo, o vi accede.

HANDLE WINAPI CreateSemaphore(
LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
LONG lInitialCount,
LONG lMaximumCount,
LPCTSTR lpName
);

lpSemaphoreAttributes

Serve ad impostare politiche di sicurezza. Messo a NULL, utilizza il default. Leggete MSDN per saperne di più

lInitialCount

Il valore iniziale del semaforo. Dev'essere >= 0 e <= lMaximumCount

lMaximumCount

Il valore massimo che il semaforo può assumere. Dev'essere >0.

lpName

Il nome assegnato al semaforo. NULL lascia il semaforo anonimo (va benissimo anche così).

ReleaseSemaphore

Incrementa il semaforo (up)

BOOL WINAPI ReleaseSemaphore(
HANDLE hSemaphore,
LONG lReleaseCount,
LPLONG lpPreviousCount
);

lReleaseCount

La quantità di cui incrementare il semaforo. Il valore dev'essere >0. Se il semaforo supera i limiti impostati in occasione della sua creazione, l'incremento non viene effettuato e la funzione restituisce FALSE.

lpPreviousCount

Puntatore ad una variabile che riceve il precedente valore del semaforo. Se il parametro è NULL il valore precedente non viene restituito.

Return Value

Restituisce zero in caso di errore. Per ottenere maggiori informazioni, chiamate GetLastError

Funzioni di attesa

Le funzioni WaitFor_ sono funzioni polimorfe che bloccano il thread corrente fino al verificarsi della condizione specificata o della scadenza del termine. Il loro comportamento cambia a seconda del tipo di oggetto che viene loro passato

- Mutex & Semafori: acquisizione (lock)
- Thread (terminazione)

WaitForSingleObject

Attende il verificarsi di un evento.

DWORD WINAPI WaitForSingleObject(
HANDLE hHandle,
DWORD dwMilliseconds
);

dwMilliseconds

Quanto a lungo attendere l'evento prima di proseguire. Va benissimo INFINITE("aspetta e basta!")

WaitForMultipleObjects

Attende un'insieme di eventi (uno o tutti).

DWORD WINAPI WaitForMultipleObjects(
DWORD nCount,
const HANDLE* lpHandles,
BOOL bWaitAll,
DWORD dwMilliseconds
);

nCount

Numero degli eventi descritti

lpHandles

Array degli descrittori (handle degli eventi)

bWaitAll

Uno solo o tutti?