3.3. Access Control

Cogent SST-DHP Driver for SST Data Highway Plus Cards : Version 1.5
	Chapter 3. Communicating with the Administrator

Before a task is allowed to read from or write to the Data Highway, it has to be granted access. The SD_OPEN request is used to acquire access and the SD_CLOSE request is used to release it. Upon successful completion of the SD_OPEN request, the sdadmin replies with a handle which is unique for that card. To access the card for read or write, the task must provide the handle in the appropriate request structure. At any one time, there may be up to 10 tasks which open a card.

As well, one of the tasks which has opened the card may request to receive unsolicited messages from the Data Highway. This is done with the SD_UNSOLICITED request.

If any of these requests is made with a card_num not between 0 and 7, SD_R_BAD_PARM is returned.

3.3.1. `SD_OPEN`

Before accessing the Data Highway or Data Highway Plus, a task must perform an SD_OPEN. This function returns one field, handle, which must be saved for use with the read or write command. The caller's task id is recorded with each call to SD_OPEN. Further references to handle are disallowed unless they are received from the same task id. If all handles have been opened for the particular card, SD_R_TOO_MANY is returned. If the card has not yet been initialized, SD_R_NOT_INITIALIZED is returned.

3.3.2. `SD_CLOSE`

Once a task has completed accessing the Data Highway, SD_CLOSE should be called to release the handle and make it available for other tasks. When a task dies, the administrator learns of its demise and automatically closes any handles it had open. If the handle is not open, or is opened by another task, SD_R_NOT_OPEN or SD_R_NOT_OWNER is returned.

3.3.3. `SD_UNSOLICITED`

For each card, only one task may be designated to receive unsolicited messages. The first task to call this function for a card is allowed to receive any command messages that arrive at the card. If this function is not called, any unsolicited messages received are discarded.

Before invoking SD_UNSOLICITED, the task should obtain a handle through the SD_OPEN function. After calling SD_UNSOLICITED, the task should continuously perform SD_READ to receive the messages and then do an SD_WRITE to reply to the commands. It is the responsibility of the application to reply to unsolicited commands.

If another task has already requested unsolicited commands, this function returns SD_R_ALREADY until the first task terminates.