Initial Setting for SI Device Use
#include <ultra64.h> /* os.h */
s32 osContInit(OSMesgQueue *mq, u8 *bitpattern, OSContStatus *status);The osContInit function initializes the SI settings and checks the status and type of SI device.
This function must be called before you call any functions to be used for initialization that are unique to each SI device. By doing this, the system checks the connection status of the SI device. If the Plf is busy, the timer waits until it is available for use by the SI device. This is because PIf is used to establish connection between the game pack right after N64 launches. While it is in use, PIf cannot be used.
The osContInit must be called before all the SI device functions are called. However, it should be called only once after the program launches or a reset is performed. It is not necessary to call this function more than twice. This function does nothing after the second call. Therefore, if the status and type of SI device need to be checked after the first osContInit call, please use the osContStartQuery function and osContGetQuery
The osContInit function returns to a bitmap pattern specified by bitpattern, the result of which controller port the direct SI device is connected to. There are two types of SI devices; one SI device can be identified as Direct Si device, which can be connected with the joybus or external joybus to establish direct connection with PIf. The other type of SI device can be identified as Pack SI device, which is used to connect to the joyport of a controller. Bit 0, 1, 2, 3 of a bitpattern correspond to controller port 0, 1, 2, 3, respectively. The Direct SI device is inserted into the controller port 0 if the bit 0 of a bitpattern is set to 1. Also, the osContInit function examines the status of the joyport and returns the result to status when the Controller is connected. The area specifed by status must be large enough to hold the number of OSContStatus structures specified by MAXCONTROLLERS, which store the status for each device inserted into the controller port.
typedef struct {
u16 type; /* Controller type */
u8 status; /* Controller Pak status */
u8 errno; /* Error from SI device */
}OSContStatus;
The message queue, mq, is the initialized message queue linked to OS_EVENT_SI. See the osSetEventMesg function to learn how to create this link. Since "mq" is used inside the function to wait for messages, the application does not need to use "mq" to wait for an end-of-function message.
0 is returned if initialization is successful, and -1 is returned if it fails to transfer data while SI is in use. It is rare for a -1 to be returned.
One of the following bits is set to 1 to the value for status->type, depending on which kind of direct- SI device is inserted to the controller port. 0 is returned when no device is inserted in the controller port.
Confirm which kind of direct-type SI device is connected to the Controller Port in the following way:
If the direct-type SI device connected to the Controller Port is a Standard Controller, then the status of that joyport can be checked with status->status. The lower bit in status->status is set to 1. If nothing is inserted in either the Controller Port or the joyport connector, or if a direct-type SI device that is not a Controller is inserted, then 0 is returned.
An Error value is set to status->errno when the function fails to read the status value of SI device. 0 is returned if the function was successful. One of the follwing values is returned should an error occur.
When it is recognized that the Controller socket was not connected, or a communication error occurs in a controller port(bitpattern's bit is zero, or status->errno is not zero), the Controller's status type and status value become invalid. You need to make sure the Controller is connected properly by looking at the bit pattern first before examining the Controller type and status.
Although it used to be performed in this function with OS 2.0e or previous versions, resetting a controller cannot be accomplished in this function with OS 2.0f or later. Normally it is not necessary to reset a controller, however it can be accomplished by using osContReset
The following sample shows how to use osContInit function within a program. The function checks each controller port to report which type of direct SI device is inserted.
void
mainproc(void)
{
OSMesgQueue intMesgQueue;
OSMesg intMesgBuf[1];
OSContStatus sdata[MAXCONTROLLERS];
u8 pattern;
int i;
osCreateMesgQueue(&intMesgQueue, intMesgBuf, 1);
osSetEventMesg(OS_EVENT_SI, &intMesgQueue, NULL);
osContInit(&intMesgQueue, &pattern, &sdata[0]);
for(i = 0; i < MAXCONTROLLERS; i++){
if(((pattern >> i) & 1) && (sdata[i].errno == 0)){
if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_NORMAL){
osSyncPrintf("Standard Controller\n");
}
else if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_MOUSE){
osSyncPrintf("Mouse\n");
}
else if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_VOICE){
osSyncPrintf("Voiced Recognition System\n");
}
else{
osSyncPrintf("Other Devices\n");
}
}else{
osSyncPrintf("Nothing is inserted in this port\n");
}
}
}
osContReset, osContStartQuery, osContStartReadData, osContGetQuery, osContGetReadData, osContSetCh, and osSetEventMesg
1999/02/01 Completely revised
1999/04/30 Changed format