Important: The information in this document is obsolete and should not be used for new development.
sdspOpen
ThesdspOpen
routine opens a secure (ASDSP) connection and causes ASDSP to perform the challenge-and-reply process that authenticates the ASDSP clients at either end of the connection. You use thePBControl
function to call thesdspOpen
routine. See "Routines" on page 5-43 for a description of thePBControl
function.
ioCompletion ProcPtr A pointer to completion routine. ioResult OSErr A result code. ioCRefNum Integer The ADSP driver reference number. csCode Integer Always sdspOpen
for this function.ccbRefNum Integer The CCB reference number for
connection end.localCID Integer The ID of this connection end. remoteCID Integer The ID of remote connection end. remoteAddress AddrBlock A remote internet address. filterAddress AddrBlock A filter for open connection end. sendSeq LongInt The initial send sequence number. sendWindow Integer The initial size of remote receive queue. recvSeq LongInt Not used for ASDSP. attnSendSeq LongInt The attention send sequence number. attnRecvSeq LongInt Not used for ASDSP. ocMode Byte The connection-opening mode. ocInterval Byte The interval between open requests. ocMaximum Byte The maximum number of retries of the open-connection request. secure Boolean A flag that determines if ASDSP authenticates the connection. sessionKey AuthKeyPtr A pointer to the session encryption key. credentialsSize LongInt The length of credentials. credentials Ptr A pointer to credentials. workspace Ptr A pointer to workspace for connection. recipient AuthIdentity The identity of recipient. issueTime UTCTime The time when credentials were issued. expiry UTCTime The time when credentials expire. initiator RecordIDPtr A pointer to record ID of initiator. hasIntermediary Boolean TRUE
if credentials has an intermediary.intermediary RecordIDPtr A pointer to record ID of intermediary. The use of parameters by the
sdspOpen
routine depends on the mode in which the routine is executed, as follows:
ocRequest ocPassive ocAccept --> ioCompletion --> ioCompletion --> ioCompletion <-- ioResult <-- ioResult <-- ioResult --> ioCRefNum --> ioCRefNum --> ioCRefNum --> csCode --> csCode --> csCode --> ccbRefNum --> ccbRefNum --> ccbRefNum <-- localCID <-- localCID <-- localCID <-- remoteCID <-- remoteCID --> remoteCID --> remoteAddress <-- remoteAddress --> remoteAddress --> filterAddress --> filterAddress -- filterAddress <-- sendSeq <-- sendSeq --> sendSeq <-- sendWindow <-- sendWindow --> sendWindow -- recvSeq -- recvSeq -- recvSeq <-- attnSendSeq <-- attnSendSeq --> attnSendSeq -- attnRecvSeq -- attnRecvSeq -- attnRecvSeq --> ocMode --> ocMode --> ocMode --> ocInterval --> ocInterval --> ocInterval --> ocMaximum --> ocMaximum --> ocMaximum --> secure <-- secure <-- secure --> sessionKey <-- sessionKey <-- sessionKey --> credentialsSize -- credentialsSize -- credentialsSize --> credentials -- credentials -- credentials --> workspace --> workspace --> workspace -- recipient --> recipient --> recipient -- issueTime <-- issueTime <-- issueTime -- expiry <-- expiry <-- expiry -- initiator <-> initiator <-> initiator -- hasIntermediary <-- hasIntermediary <-- hasIntermediary -- intermediary <-> intermediary <-> intermediary Key: --> input <-- output <-> input and output -- not used
Field Description
csCode
- The routine selector, always equal to
sdspOpen
for this routine.ccbRefNum
- This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.
localCID
- This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.
remoteCID
- The identification number of the remote connection end. This parameter is returned by the
sdspOpen
routine in theocRequest
andocPassive
modes. A connection server must provide this number to thesdspOpen
routine when the server executes the routine inocAccept
mode; in this case, the connection server obtains theremoteCID
value from thedspCLListen
routine.remoteAddress
- The internet address of the remote socket with which you wish to establish communications. This address consists of a 2-byte network number, a 1-byte node ID, and a 1-byte socket number. You must provide this parameter when you call the
sdspOpen
routine in
theocRequest
orocAccept
mode. When you call thesdspOpen
routine in theocAccept
mode, you must use the value for theremoteAddress
parameter that was returned by thedspCLListen
routine. This parameter is returned by thesdspOpen
routine when you call the routine in theocPassive
mode.filterAddress
- This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.
sendSeq
- The sequence number of the first byte that the local connection end will send to the remote connection end. ASDSP uses this number
to coordinate communications and to check for errors. ASDSP returns a value for thesendSeq
parameter when you execute
thesdspOpen
routine in theocRequest
orocPassive
mode. When you execute thesdspOpen
routine in theocAccept
mode
, you must specify the value for thesendSeq
parameter that was returned by thedspCLListen
routine.sendWindow
- The sequence number of the last byte that the remote connection end has buffer space to receive. ASDSP uses this number to coordinate communications and to check for errors. ASDSP returns a value for the
sendWindow
parameter when you execute thesdspOpen
routine in theocRequest
orocPassive
mode. When you execute thesdspOpen
routine in theocAccept
mode, you must specify the value for thesendWindow
parameter that was returned by thedspCLListen
routine.recvSeq
- This field is not used by ASDSP.
attnSendSeq
- The sequence number of the next attention packet that the local connection end will transmit. ASDSP uses this number to coordinate communications and to check for errors. ASDSP returns a value for the
attnSendSeq
parameter when you execute thesdspOpen
routine in theocRequest
orocPassive
mode. When you execute thesdspOpen
routine in theocAccept
mode, you must specify the value for theattnSendSeq
parameter that was returned by thedspCLListen
routine.attnRecvSeq
- This field is not used by ASDSP.
ocMode
- The mode in which the
sdspOpen
routine is to operate, as follows:ocInterval
- This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.
ocMaximum
- This field is used in the same way that it is used for ADSP. See the description of this field under "dspOpen" beginning on page 5-48.
secure
- A flag that determines whether ASDSP authenticates the connection. On input for the initiator end, you must set this value to
TRUE
if you want ASDSP to authenticate the connection. You must provide a value for thesecure
parameter when you execute thesdspOpen
routine in theocRequest
mode. ASDSP returns a value ofTRUE
for this parameter to the recipient for all modes if the session was authenticated.sessionkey
- A pointer to a buffer containing the session key returned by
the Authentication Manager'sAuthGetCredentials
orAuthTradeProxyForCredentials
function. The initiator connection end must provide an input value for this parameter.
For the recipient connection end, ASDSP breaks out the session
key from the credentials block and returns a copy of the session key as the value of this parameter. See the description of the data structures that you need to allocate for ASDSP in the section "Opening a Secure Connection" beginning on page 5-30 for more information about the buffer.credentialsSize
- The size in bytes of credentials returned by the Authentica-
tion Manager'sAuthTradeProxyForCredentials
orAuthGetCredentials
function.You must provide a value for thecredentialsSize
parameter when you execute thesdspOpen
routine in theocRequest
mode. This parameter is not used for the recipient end of the connection when you call thesdspOpen
routine inocAccept
mode orocPassive
mode.credentials
- A pointer to the credentials for this session that the Authentica-
tion Manager'sAuthTradeProxyForCredentials
orAuthGetCredentials
function returned when you called it. Specify the size in bytes of the credential block pointed to by this parameter as the value of thecredentialsSize
parameter when you call thesdspOpen
routine in theocRequest
mode. This parameter is not used for the recipient end of the connection when you call thesdspOpen
routine inocAccept
mode orocPassive
mode. See the chapter "Authentication Manager" in Inside Macintosh: AOCE Application Programming Interfaces.workspace
- A pointer to a buffer that you allocate as workspace for the
sdspOpen
routine's internal use. The memory for the buffer that you allocate must be aligned on an even boundary and must be equal in size to thesdspWorkSize
constant, which is 2048 bytes.recipient
- When the value of the
ocMode
parameter isocAccept
, you specify the identity of the connection server as the value of therecipient
parameter. When the value of theocMode
parameter
isocPassive
, you specify the identity of the socket that is the recipient of the request call as the value of therecipient
parameter. This field is not used when theocMode
parameter
value isocRequest
.issueTime
- The time when the authentication credentials were issued. Together with the
expiry
parameter value, theissueTime
parameter specifies the period of time for which the credentials are valid. ASDSP extracts the value for theissueTime
parameter from the decrypted credentials. ASDSP returns this value when the mode isocPassive
orocAccept
. TheissueTime
field is not used when theocMode
parameter value isocRequest
.expiry
- The time when the authentication credentials expire. Together with the
issueTime
parameter value, theexpiry
parameter specifies the duration for which the credentials are valid. ASDSP extracts the value for theexpiry
parameter from the decrypted credentials. This field is not used when theocMode
parameter value isocRequest
.initiator
- A pointer to the record ID of the initiator that ASDSP returns when the value of the
ocMode
parameter isocAccept
orocPassive
. ASDSP extracts this value from the encrypted credentials. This field is not used when theocMode
parameter value isocRequest
.hasIntermediary
- A flag that ASDSP sets if the credentials have an intermediary.
When this flag is set, a proxy was used; an intermediary used
theAuthTradeProxyForCredentials
function to obtain the credentials used in the authentication process. ThesdspOpen
routine returns this value when theocMode
parameter value isocPassive
orocAccept
.intermediary
- A pointer to a buffer that is used to store the record ID of the inter-
mediary, if ASDSP finds an intermediary in the credentials. ThesdspOpen
routine returns this value when theocMode
parameter value isocPassive
orocAccept
.DESCRIPTION
ThesdspOpen
routine opens a secure connection end if the identities of both the initiator and the recipient connection ends can be proven in the authentication process. You set theocMode
field of the parameter block to specify the opening mode that thesdspOpen
routine is to use. ThesdspOpen
routine puts a connection end into one of the three following opening modes:
- In the
ocRequest
mode, ASDSP attempts to open a connection with the socket at the internet address you specify as theremoteAddress
parameter.- In the
ocPassive
mode, the connection end waits to receive an open-connection request from a remote connection end. You can use thefilterAddress
parameter
to restrict the addresses from which you will accept a connection request.- In the
ocAccept
mode, connection servers complete open-connection dialogs. When a connection server is informed by its connection listener that the connection listener has received an open-connection request, the connection server calls thedspInit
routine to establish a connection end and then calls thesdspOpen
routine inocAccept
mode to complete the connection. Connection listeners and connection servers are described in "Creating and Using a Connection Listener" beginning on page 5-22 and in "Establishing and Terminating an ADSP Connection" beginning on page 5-44. See "Connection Listeners" on page 5-7 for a brief introduction to connection listeners.Except for the authentication process, these three modes are used by ASDSP and ADSP in the same way and their behavior is the same. See the description of how these modes are used in "dspOpen" beginning on page 5-48.
If ASDSP cannot successfully complete the authentication process, ASDSP tears down the connection and the
sdspOpen
calls made by both the initiator and the recipient return a result code reporting the reason why the authentication process failed. For the conditions that can cause the authentication process to fail, see the list of result codes that follows.
ASSEMBLY-LANGUAGE INFORMATION
To execute thesdspOpen
routine from assembly language, call the_Control
trap macro with a value ofsdspOpen
in thecsCode
field of the parameter block.RESULT CODES