Part IV: Libraries

87 SSL Library Macros

SSL Library Macro Constants

Attribute Values

SSL Library Macros

SslContextGet_AppInt32

SslContextGet_AppPtr

SslContextGet_AutoFlush

SslContextGet_BufferedReuse

SslContextGet_CipherSuite

SslContextGet_CipherSuiteInfo

SslContextGet_CipherSuites

SslContextGet_ClientCertRequest

SslContextGet_Compat

SslContextGet_DontSendShutdown

SslContextGet_DontWaitForShutdown

SslContextGet_Error

SslContextGet_HsState

SslContextGet_InfoCallback

SslContextGet_InfoInterest

SslContextGet_IoFlags

SslContextGet_IoStruct

SslContextGet_IoTimeout

SslContextGet_LastAlert

SslContextGet_LastApi

SslContextGet_LastIo

SslContextGet_Mode

SslContextGet_PeerCert

SslContextGet_PeerCommonName

SslContextGet_ProtocolVersion

SslContextGet_RbufSize

SslContextGet_ReadBufPending

SslContextGet_ReadOutstanding

SslContextGet_ReadRecPending

SslContextGet_ReadStreaming

SslContextGet_SessionReused

SslContextGet_Socket

SslContextGet_SslSession

SslContextGet_SslVerify

SslContextGet_Streaming

SslContextGet_VerifyCallback

SslContextGet_WbufSize

SslContextGet_WriteBufPending

SslContextSet_AppInt32

SslContextSet_AppPtr

SslContextSet_AutoFlush

SslContextSet_BufferedReuse

SslContextSet_CipherSuites

SslContextSet_Compat

SslContextSet_DontSendShutdown

SslContextSet_DontWaitForShutdown

SslContextSet_Error

SslContextSet_InfoCallback

SslContextSet_InfoInterest

SslContextSet_IoFlags

SslContextSet_IoStruct

SslContextSet_IoTimeout

SslContextSet_LastAlert

SslContextSet_Mode

SslContextSet_ProtocolVersion

SslContextSet_RbufSize

SslContextSet_ReadStreaming

SslContextSet_Socket

SslContextSet_SslSession

SslContextSet_VerifyCallback

SslContextSet_WbufSize

SslLibGet_AppInt32

SslLibGet_AppPtr

SslLibGet_AutoFlush

SslLibGet_BufferedReuse

SslLibGet_CipherSuites

SslLibGet_Compat

SslLibGet_DontSendShutdown

SslLibGet_DontWaitForShutdown

SslLibGet_InfoCallback

SslLibGet_InfoInterest

SslLibGet_Mode

SslLibGet_ProtocolVersion

SslLibGet_RbufSize

SslLibGet_ReadStreaming

SslLibGet_VerifyCallback

SslLibGet_WbufSize

SslLibSet_AppInt32

SslLibSet_AppPtr

SslLibSet_AutoFlush

SslLibSet_BufferedReuse

SslLibSet_CipherSuites

SslLibSet_Compat

SslLibSet_DontSendShutdown

SslLibSet_DontWaitForShutdown

SslLibSet_InfoCallback

SslLibSet_InfoInterest

SslLibSet_Mode

SslLibSet_ProtocolVersion

SslLibSet_RbufSize

SslLibSet_ReadStreaming

SslLibSet_VerifyCallback

SslLibSet_WbufSize

This chapter provides reference documentation for the macros that your application uses to set and get SslLib and SslContext attribute values. As well, the constants representing those attributes are listed in this chapter.

This chapter is divided into the following sections:

SSL Library Macro Constants

SSL Library Macros

The header file SslLibMac.h declares the API that this chapter describes.

Documentation for the functions that these macros employ can be found in Chapter 86, "SSL Library." A detailed description of each attribute can be found under "Attributes."

SSL Library Macro Constants ^TOP^

Attribute Values ^TOP^

Purpose

These constants represent the attributes that you can set or get by calling SslContextGet...(), SslContextSet...(), SslLibGet...(), or SslLibSet...(). The macros documented in "SSL Library Macros" call the appropriate function and supply the proper attribute value. Accordingly, applications should use these macros instead of calling the set or get functions directly.

Complete documentation for the attributes that these values represent can be found in Chapter 8, "Secure Sockets Layer (SSL)."

Declared In

SslLibMac.h

Constants

#define sslAttrAppInt32 0x0F0A0A13

#define sslAttrAppPtr 0x0F090911

#define sslAttrAutoFlush 0x0F070712

#define sslAttrBufferedReuse 0x0F080812

#define sslAttrCertPeerCert 0x0100FF01

#define sslAttrCertPeerCommonName 0x0180FF01

#define sslAttrCertSslVerify 0x0101FF04

#define sslAttrClientCertRequest 0x0F20FF12

#define sslAttrCompat 0x0F010113

#define sslAttrCspCipherSuite 0x0001FF01

#define sslAttrCspCipherSuiteInfo 0x0082FF01

#define sslAttrCspCipherSuites 0x00008101

#define sslAttrCspSslSession 0x00808001

#define sslAttrDontSendShutdown 0x0F212112

#define sslAttrDontWaitForShutdown 0x0F222212

#define sslAttrError 0x0F111113

#define sslAttrErrorState 0x0F05FF14

#define sslAttrHsState 0x0F12FF13

#define sslAttrInfoCallback 0x0F0E0E15

#define sslAttrInfoInterest 0x0F020213

#define sslAttrIoFlags 0x04030303

#define sslAttrIoSocket 0x04010103

#define sslAttrIoStruct 0x04008001

#define sslAttrIoTimeout 0x04020203

#define sslAttrLastAlert 0x0F131313

#define sslAttrLastApi 0x0F1FFF12

#define sslAttrLastIo 0x0F1EFF12

#define sslAttrLibAppInt32 0x0F0F0F03

#define sslAttrLibAppPtr 0x0F0E0E01

#define sslAttrLibAutoFlush 0x0F0C0C02

#define sslAttrLibBufferedReuse 0x0F0D0D02

#define sslAttrLibCompat 0x0F010103

#define sslAttrLibDontSendShutdown 0x0F121202

#define sslAttrLibDontWaitForShutdown 0x0F131302

#define sslAttrLibInfoCallback 0x0F080805

#define sslAttrLibInfoInterest 0x0F020203

#define sslAttrLibMode 0x0F040403

#define sslAttrLibProtocolVersion 0x0F030303

#define sslAttrLibRbufSize 0x0F101003

#define sslAttrLibReadStreaming 0x0F0B0B02

#define sslAttrLibVerifyCallback 0x0F0A0A05

#define sslAttrLibWbufSize 0x0F111103

#define sslAttrMode 0x0F048013

#define sslAttrProtocolVersion 0x0F030313

#define sslAttrRbufSize 0x0F1B8113

#define sslAttrReadBufPending 0x0F16FF13

#define sslAttrReadOutstanding 0x0F18FF13

#define sslAttrReadRecPending 0x0F17FF13

#define sslAttrReadStreaming 0x0F060612

#define sslAttrSessionReused 0x0F14FF12

#define sslAttrStreaming 0x0F1DFF12

#define sslAttrVerifyCallback 0x0F101015

#define sslAttrWbufSize 0x0F1C8213

#define sslAttrWriteBufPending 0x0F15FF13

SSL Library Macros ^TOP^

SslContextGet_AppInt32 Macro ^TOP^

Purpose

Obtain the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_AppInt32 (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns the 32-bit value.

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslContextSet_AppInt32(), SslLibGet_AppInt32()

SslContextGet_AppPtr Macro ^TOP^

Purpose

Obtain the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_AppPtr (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

The address of a pointer variable into which the AppPtr attribute value is written.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslContextSet_AppPtr(), SslLibGet_AppPtr()

SslContextGet_AutoFlush Macro ^TOP^

Purpose

Determine whether SslSend() and SslWrite() attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_AutoFlush (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns 0 if data is buffered, or 1 if the data is sent immediately.

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslContextSet_AutoFlush(), SslLibGet_AutoFlush()

SslContextGet_BufferedReuse Macro ^TOP^

Purpose

Determine if the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_BufferedReuse (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns 0 if the last message is not buffered, or a non-zero value if it is.

See Also

"BufferedReuse," SslContextSet_BufferedReuse(), SslLibGet_BufferedReuse()

SslContextGet_CipherSuite Macro ^TOP^

Purpose

Identify the cipher suite being used by the current connection.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CipherSuite (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Pointer to a pointer variable; upon return the pointer variable points to two bytes which identify the cipher suite being used by the current connection. If these two bytes are both set to zero, no cipher suite is being used. Otherwise, see "Cipher Suites" for the list of possible cipher suites.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"CipherSuite"

SslContextGet_CipherSuiteInfo Macro ^TOP^

Purpose

Obtain information relevant to the current cipher suite. This macro populates a SslCipherSuiteInfo structure that must have been allocated by the caller.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CipherSuiteInfo (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Pointer to the SslCipherSuiteInfo structure that is to be filled in.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"CipherSuiteInfo", SslContextGet_CipherSuite()

SslContextGet_CipherSuites Macro ^TOP^

Purpose

Obtain the list of cipher suites that the SSL protocol is attempting to use.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_CipherSuites (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Supply the address of a pointer variable; upon return the pointer variable will point to a series of bytes, where the first two bytes indicate the number of bytes that follow, and each pair of bytes after that is one of the values listed under "Cipher Suites." See "CipherSuites" for more details on this attribute.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"CipherSuites", SslContextSet_CipherSuites(), SslLibGet_CipherSuites()

SslContextGet_ClientCertRequest Macro ^TOP^

Purpose

Determine whether or not the SSL server requested a client certificate.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ClientCertRequest (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns 0 if the server did not request a client certificate, or 1 if the server did request one.

See Also

"ClientCertRequest"

SslContextGet_Compat Macro ^TOP^

Purpose

Determine which SSL protocol compatibility flags are set. These flags enable compatiblity with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Compat (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns a 32-bit integer value that is the logical OR of those compatibility flags that have been set. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

See Also

"Compat," SslContextSet_Compat(), SslLibGet_Compat()

SslContextGet_DontSendShutdown Macro ^TOP^

Purpose

Determine whether or not an SslClose() will send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_DontSendShutdown (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns zero if SslClose() does send a shutdown message to the server, or a non-zero value if it doesn't.

See Also

"DontSendShutdown," SslContextSet_DontSendShutdown(), SslLibGet_DontSendShutdown(), SslContextGet_DontWaitForShutdown()

SslContextGet_DontWaitForShutdown Macro ^TOP^

Purpose

Determine whether or not the SslContext will wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslContextGet_DontWaitForShutdown (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns zero if the SslContext waits for a shutdown message, or a non-zero value if it doesn't.

See Also

"DontWaitForShutdown," SslLibGet_DontWaitForShutdown(), SslContextGet_DontSendShutdown(), SslContextSet_DontWaitForShutdown()

SslContextGet_Error Macro ^TOP^

Purpose

Obtain the error value produced when a fatal error occurs while using an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Error (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns 0 if there was no error, or one of the error codes listed under "SSL Library Errors" if an error did occur.

Comments

Once the error attribute is set, the SslLib network APIs will continue to return this error (unless the error is a non-fatal error) until either an SSL Reset is performed on the SslContext or the error is cleared.

See Also

"Error," SslContextSet_Error()

SslContextGet_HsState Macro ^TOP^

Purpose

Determine the state that the SSL protocol is currently in.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_HsState (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

One of the values are defined under "SSL Protocol States" to indicate the SSL protocol handshake.

See Also

"HsState"

SslContextGet_InfoCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function called when various situations occur during the usage of an SslContext. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_InfoCallback (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslContextSet_InfoCallback(), SslLibGet_InfoCallback()

SslContextGet_InfoInterest Macro ^TOP^

Purpose

Obtain the flags that specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_InfoInterest (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The logical ORing of the sslFlgInfo... values listed under "InfoInterest Values."

See Also

"InfoInterest," SslContextSet_InfoInterest(), SslLibGet_InfoInterest()

SslContextGet_IoFlags Macro ^TOP^

Purpose

Obtain the flags value that is passed to Net Library calls.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_IoFlags (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The 32-bit flags value that is passed to Net Library calls.

Comments

Since we will normally be using TCP connections with SSL, this attribute is more included for completeness rather than utility. Read about this flags value in the NetLibSend() and NetLibReceive() documentation.

See Also

"IoFlags," SslContextSet_IoFlags()

SslContextGet_IoStruct Macro ^TOP^

Purpose

Obtain the SslContext's internal SslSocket structure.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_IoStruct (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ v

Pass the address of a pointer variable. Upon return the variable will point to the SslContext's SslSocket structure.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"IoStruct," SslContextSet_IoStruct()

SslContextGet_IoTimeout Macro ^TOP^

Purpose

Obtain the SslContext's internal timeout value.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_IoTimeout (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The internal timeout value, in seconds.

Comments

When a call is made into the SslLib API which does not specify a timeout, this internal value is used. If the API call has a timeout value, it overrides this internal value.

By default, the SslContext's internal timeout value is 10 seconds.

See Also

"IoTimeout," SslContextSet_IoTimeout()

SslContextGet_LastAlert Macro ^TOP^

Purpose

Obtain the last alert value received from the server.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_LastAlert (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

One of the values listed under "SSL Server Alerts."

Comments

Non-fatal alerts have a value of the form 0x01XX, while fatal alerts have the form 0x02XX. SslLib will fail on fatal alerts and continue on non-fatal alerts.

See Also

"LastAlert", SslContextSet_LastAlert()

SslContextGet_LastApi Macro ^TOP^

Purpose

Identify the last SslLib API call that was made.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_LastApi (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns one of the values listed under "LastApi Attribute Values."

See Also

"LastApi"

SslContextGet_LastIo Macro ^TOP^

Purpose

Identify the last network operation performed.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_LastIo (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns one of the values listed under "LastIO Attribute Values."

See Also

"LastIo"

SslContextGet_Mode Macro ^TOP^

Purpose

Obtain the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Mode (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns one of the values listed under "Mode Attribute Values."

See Also

"Mode," SslContextSet_Mode(), SslLibGet_Mode()

SslContextGet_PeerCert Macro ^TOP^

Purpose

Obtain the certificate supplied by the other end of the SSL connection, if one is available.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_PeerCert (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Pass the address of a pointer variable. Upon return that variable will reference an SslExtendedItems data structure internal to the SslContext that contains the peer certificate.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

The returned pointer references an SslExtendedItems data structure which is internal to the SslContext and will be disposed of by the SslContext. If a new connection is established with the SslContext, previously returned PeerCert pointers will become invalid. If the application wishes to preserve the certificate for an extended period, it should make a local copy.

See Also

"PeerCert", "The SslExtendedItems Structure," SslContextGet_PeerCommonName()

SslContextGet_PeerCommonName Macro ^TOP^

Purpose

Obtain the server certificate's common name.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_PeerCommonName (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Supply the address of a pointer variable. Upon return the variable will point to an SslExtendedItems structure containing the common name for the server's certificate (or, if there is no common name available, the variable will be set to NULL.)

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Example

The following code shows how to access the common name from within the SslExtendedItem structure:

SslExtendedItems *cert; 
SslExtendedItem *commonName; 
UInt16 length; 
UInt8 *bytes; 
 
SslContextGet_PeerCert(ssl, &cert); 
if (cert == NULL) goto err; 
SslContextGet_PeerCommonName(ssl,&commonName); 
length=commonName->len; 
bytes=((Int8 *)cert)+commonName->offset; 
// bytes now points to the common name, and length contains 
// the length of the common name string. 

See Also

"PeerCommonName", "The SslExtendedItems Structure"

SslContextGet_ProtocolVersion Macro ^TOP^

Purpose

Determine which version of the SSL protocol is being used.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ProtocolVersion (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

One of the values listed under "Protocol Versions."

See Also

"ProtocolVersion," SslContextSet_ProtocolVersion(), SslLibGet_ProtocolVersion()

SslContextGet_RbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the SslContext's read buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_RbufSize (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The read buffer size. This is a value that ranges from 0 to 16384.

See Also

"RbufSize," SslContextSet_RbufSize(), SslLibGet_RbufSize()

SslContextGet_ReadBufPending Macro ^TOP^

Purpose

Obtains the number of data bytes that are currently buffered for reading from the SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadBufPending (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The number of buffered read bytes.

Comments

The returned number of bytes also includes bytes used for encoding SSL records.

See Also

"ReadBufPending"

SslContextGet_ReadOutstanding Macro ^TOP^

Purpose

Obtain the number of bytes in the current record that have not been read from the network

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadOutstanding (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The number of bytes outstanding in current SSL record.

See Also

"ReadOutstanding"

SslContextGet_ReadRecPending Macro ^TOP^

Purpose

Obtain the number of application data bytes that are buffered, awaiting the application to read.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadRecPending (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The number of buffered SSL record bytes.

See Also

"ReadRecPending," SslContextGet_ReadOutstanding()

SslContextGet_ReadStreaming Macro ^TOP^

Purpose

Determine whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_ReadStreaming (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns a zero value if data is only returned when the full record has been downloaded, or a non-zero value otherwise.

See Also

"ReadStreaming," SslContextSet_ReadStreaming(), SslLibGet_ReadStreaming()

SslContextGet_SessionReused Macro ^TOP^

Purpose

Determine whether the SSL handshake was able to perform a truncated handshake by re-using the SSL session values in the SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_SessionReused (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns a non-zero value if the SSL handshake was able to perform a truncated handshake by re-using the SSL session values in the SslContext, or zero if it wasn't.

See Also

"SessionReused"

SslContextGet_Socket Macro ^TOP^

Purpose

Obtain the Net Library socket that the SslContext should use to perform its network I/O operations.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Socket (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The NetSocketRef for the SslContext's Net Library socket.

See Also

"Socket," SslContextSet_Socket()

SslContextGet_SslSession Macro ^TOP^

Purpose

Get the SslContext's SslSession structure. This is either the SslSession currently being used, or the SslSession for this SslContext to use to establish its next connection.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_SslSession (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Pass the address of a pointer variable; upon return this variable will point to the SslContext's SslSession structure.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"SslSession," SslContextSet_SslSession()

SslContextGet_SslVerify Macro ^TOP^

Purpose

Obtain a pointer to the structure containing the verification state. This structure can be helpful when attempting to resolve any problems that SslLib may have encountered during certificate verifcation.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_SslVerify (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Supply the address of a pointer variable. Upon return the variable will point to an SslVerify structure containing the preserved state. See "The SslVerify Structure" for a description of this structure.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"SslVerify"

SslContextGet_Streaming Macro ^TOP^

Purpose

Determine if the current SslContext is doing read-streaming.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_Streaming (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

Returns 1 if the current SslContext is doing read-streaming.

See Also

"Streaming"

SslContextGet_VerifyCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function used to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_VerifyCallback (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

→ v

Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslContextSet_VerifyCallback(), SslLibGet_VerifyCallback()

SslContextGet_WbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the SslContext's write buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_WbufSize (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The write buffer size. This is a value that ranges from 0 to 16384.

See Also

"WbufSize," SslContextSet_WbufSize(), SslLibGet_WbufSize()

SslContextGet_WriteBufPending Macro ^TOP^

Purpose

Obtains the number of bytes in the SslContext's write buffer waiting to be sent to the remote machine.

Declared In

SslLibMac.h

Prototype

#define SslContextGet_WriteBufPending (
   refnum,
    ssl
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext from which the value is to be retrieved.

Returns

The number of buffered bytes waiting to be sent.

Comments

This value will normally be zero unless AutoFlush is disabled and/or non-blocking I/O is being used.

See Also

"WriteBufPending", SslContextGet_AutoFlush()

SslContextSet_AppInt32 Macro ^TOP^

Purpose

Set the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_AppInt32 (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The 32-bit value.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslContextGet_AppInt32(), SslLibSet_AppInt32()

SslContextSet_AppPtr Macro ^TOP^

Purpose

Set the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_AppPtr (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The AppPtr attribute value.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslContextDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslContextGet_AppPtr(), SslLibSet_AppPtr()

SslContextSet_AutoFlush Macro ^TOP^

Purpose

Specify whether SslSend() and SslWrite() should attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_AutoFlush (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

Pass 0 to have the data buffered, or 1 to have the data sent immediately.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslContextGet_AutoFlush(), SslLibSet_AutoFlush()

SslContextSet_BufferedReuse Macro ^TOP^

Purpose

Specify whether the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_BufferedReuse (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

Supply a value of 0 if the last message should not be buffered, or a non-zero value if it should.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"BufferedReuse," SslContextGet_BufferedReuse(), SslLibSet_BufferedReuse()

SslContextSet_CipherSuites Macro ^TOP^

Purpose

Specify the list of cipher suites that the SSL protocol should attempt to use.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_CipherSuites (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

Pointer to an array of byte pairs. The first two bytes contain the number of bytes that follow, and each successive pair is one of the values listed under "Cipher Suites."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"CipherSuites", SslContextGet_CipherSuites(), SslLibSet_CipherSuites()

SslContextSet_Compat Macro ^TOP^

Purpose

Determine how compatible the SSL protocol should be with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Compat (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The logical OR of those compatibility flags that correspond to the SSL protocol incompatibilities that should be accommodated. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"Compat," SslContextGet_Compat(), SslLibSet_Compat()

SslContextSet_DontSendShutdown Macro ^TOP^

Purpose

Specify whether or not an SslClose() should send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_DontSendShutdown (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

Zero if SslClose() should send a shutdown message, or a non-zero value if it shouldn't.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"DontSendShutdown," SslContextGet_DontSendShutdown(), SslLibSet_DontSendShutdown(), SslContextSet_DontWaitForShutdown()

SslContextSet_DontWaitForShutdown Macro ^TOP^

Purpose

Specify whether or not the SslContext should wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslContextSet_DontWaitForShutdown (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

Zero if the SslContext waits for a shutdown message, or a non-zero value if it doesn't.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"DontWaitForShutdown," SslContextGet_DontWaitForShutdown(), SslContextSet_DontSendShutdown(), SslLibSet_DontWaitForShutdown()

SslContextSet_Error Macro ^TOP^

Purpose

Associate a new error value with an SslContext. This value overrides any error value produced when a fatal error occurs while using an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Error (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The new error value. A value of 0 corresponds to "no error."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

Once the error attribute is set, the SslLib network APIs will continue to return this error (unless the error is a non-fatal error) until either an SSL Reset is performed on the SslContext or the error is cleared.

See Also

"Error," SslContextGet_Error()

SslContextSet_InfoCallback Macro ^TOP^

Purpose

Specify the callback function called when various situations occur during the usage of an SslContext. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_InfoCallback (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

A pointer to a callback function of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslContextGet_InfoCallback(), SslLibSet_InfoCallback()

SslContextSet_InfoInterest Macro ^TOP^

Purpose

Specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_InfoInterest (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The logical ORing of the sslFlgInfo... values listed under "InfoInterest Values."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"InfoInterest," SslContextGet_InfoInterest(), SslLibSet_InfoInterest()

SslContextSet_IoFlags Macro ^TOP^

Purpose

Specify the flags value that is to be passed to Net Library calls.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_IoFlags (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The 32-bit flags value to be passed to Net Library calls.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

Since we will normally be using TCP connections with SSL, this attribute is more included for completeness rather than utility. Read about this flags value in the NetLibSend() and NetLibReceive() documentation.

See Also

"IoFlags," SslContextGet_IoFlags()

SslContextSet_IoStruct Macro ^TOP^

Purpose

Specify the SslSocket structure to be used by an SslContext.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_IoStruct (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

Pointer to the SslSocket structure.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"IoStruct," SslContextSet_IoStruct()

SslContextSet_IoTimeout Macro ^TOP^

Purpose

Specify the SslContext's internal timeout value.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_IoTimeout (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The new internal timeout value, in seconds.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

When a call is made into the SslLib API which does not specify a timeout, this internal value is used. If the API call has a timeout value, it overrides this internal value.

By default, the SslContext's internal timeout value is 10 seconds.

See Also

"IoTimeout," SslContextGet_IoTimeout()

SslContextSet_LastAlert Macro ^TOP^

Purpose

Override the last alert value received from the server.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_LastAlert (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The new "last alert" value. This should be one of the values listed under "SSL Server Alerts."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

Non-fatal alerts have a value of the form 0x01XX, while fatal alerts have the form 0x02XX. SslLib will fail on fatal alerts and continue on non-fatal alerts.

See Also

"LastAlert", SslContextGet_LastAlert()

SslContextSet_Mode Macro ^TOP^

Purpose

Specify the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Mode (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

One of the values listed under "Mode Attribute Values."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"Mode," SslContextGet_Mode(), SslLibSet_Mode()

SslContextSet_ProtocolVersion Macro ^TOP^

Purpose

Specify the version of the SSL protocol to use.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_ProtocolVersion (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

One of the values listed under "Protocol Versions."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslLib implements only SSLv3 at this point in time, so modification of this value is not a good idea.

See Also

"ProtocolVersion," SslContextGet_ProtocolVersion(), SslLibSet_ProtocolVersion()

SslContextSet_RbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the SslContext's read buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_RbufSize (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The read buffer size. This is a value that ranges from 0 to 16384.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"RbufSize," SslContextGet_RbufSize(), SslLibSet_RbufSize()

SslContextSet_ReadStreaming Macro ^TOP^

Purpose

Specify whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_ReadStreaming (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

A zero value if data is only to be returned when the full record has been downloaded, or a non-zero value otherwise.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"ReadStreaming," SslContextGet_ReadStreaming(), SslLibSet_ReadStreaming()

SslContextSet_Socket Macro ^TOP^

Purpose

Specify the Net Library socket that the SslContext should use to perform its network I/O operations.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_Socket (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The NetSocketRef for the Net Library socket.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"Socket," SslContextGet_Socket()

SslContextSet_SslSession Macro ^TOP^

Purpose

Specify the SslContext's SslSession structure. This is the SslSession for this SslContext to use to establish its next connection.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_SslSession (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

A pointer to the SslSession structure.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"SslSession," SslContextGet_SslSession()

SslContextSet_VerifyCallback Macro ^TOP^

Purpose

Specify the callback function to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_VerifyCallback (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

A pointer to a callback function of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslContextGet_VerifyCallback(), SslLibSet_VerifyCallback()

SslContextSet_WbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the SslContext's write buffer.

Declared In

SslLibMac.h

Prototype

#define SslContextSet_WbufSize (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ ssl

The SslContext on which to operate.

→ v

The write buffer size. This is a value that ranges from 0 to 16384.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"WbufSize," SslContextGet_WbufSize(), SslLibSet_WbufSize()

SslLibGet_AppInt32 Macro ^TOP^

Purpose

Obtain the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AppInt32 (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns the 32-bit value.

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslLibSet_AppInt32(), SslContextGet_AppInt32()

SslLibGet_AppPtr Macro ^TOP^

Purpose

Obtain the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AppPtr (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

→ v

The address of a pointer variable into which the AppPtr attribute value is written.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslLibSet_AppPtr(), SslContextGet_AppPtr()

SslLibGet_AutoFlush Macro ^TOP^

Purpose

Determine whether SslSend() and SslWrite() attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_AutoFlush (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns 0 if data is buffered, or 1 if the data is sent immediately.

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslLibSet_AutoFlush(), SslContextGet_AutoFlush()

SslLibGet_BufferedReuse Macro ^TOP^

Purpose

Determine if the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_BufferedReuse (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns 0 if the last message is not buffered, or a non-zero value if it is.

See Also

"BufferedReuse," SslLibSet_BufferedReuse(), SslContextGet_BufferedReuse()

SslLibGet_CipherSuites Macro ^TOP^

Purpose

Obtain the list of cipher suites that the SSL protocol is attempting to use. This list is inherited from the SslLib when an SslContext is created.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_CipherSuites (
   refnum,
    ssl,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

→ v

Supply the address of a pointer variable; upon return the pointer variable will point to a series of bytes, where the first two bytes indicate the number of bytes that follow, and each pair of bytes after that is one of the values listed under "Cipher Suites." See "CipherSuites" for more details on this attribute.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"CipherSuites", SslLibSet_CipherSuites(), SslContextGet_CipherSuites()

SslLibGet_Compat Macro ^TOP^

Purpose

Determine which SSL protocol compatibility flags are set. These flags enable compatiblity with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_Compat (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns a 32-bit integer value that is the logical OR of those compatibility flags that have been set. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

See Also

"Compat," SslLibSet_Compat(), SslContextGet_Compat()

SslLibGet_DontSendShutdown Macro ^TOP^

Purpose

Determine whether or not an SslClose() will send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_DontSendShutdown (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns zero if SslClose() does send a shutdown message to the server, or a non-zero value if it doesn't.

See Also

"DontSendShutdown," SslLibSet_DontSendShutdown(), SslContextGet_DontSendShutdown(), SslLibGet_DontWaitForShutdown()

SslLibGet_DontWaitForShutdown Macro ^TOP^

Purpose

Determine whether or not the SslLib will wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslLibGet_DontWaitForShutdown (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns zero if the SslLib waits for a shutdown message, or a non-zero value if it doesn't.

See Also

"DontWaitForShutdown," SslContextGet_DontWaitForShutdown(), SslLibGet_DontSendShutdown(), SslLibSet_DontWaitForShutdown()

SslLibGet_InfoCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function called when various situations occur during the usage of an SslLib. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_InfoCallback (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

→ v

Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslLibSet_InfoCallback(), SslContextGet_InfoCallback()

SslLibGet_InfoInterest Macro ^TOP^

Purpose

Obtain the flags that specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_InfoInterest (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

The logical ORing of the sslFlgInfo...values listed under "InfoInterest Values."

See Also

"InfoInterest," SslLibSet_InfoInterest(), SslContextGet_InfoInterest()

SslLibGet_Mode Macro ^TOP^

Purpose

Obtain the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_Mode (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns one of the values listed under "Mode Attribute Values."

See Also

"Mode," SslLibSet_Mode(), SslContextGet_Mode()

SslLibGet_ProtocolVersion Macro ^TOP^

Purpose

Determine which version of the SSL protocol is being used.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_ProtocolVersion (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

One of the values listed under "Protocol Versions."

See Also

"ProtocolVersion," SslLibSet_ProtocolVersion(), SslContextGet_ProtocolVersion()

SslLibGet_RbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the read buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_RbufSize (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

The read buffer size. This is a value that ranges from 0 to 16384.

See Also

"RbufSize," SslLibSet_RbufSize(), SslContextGet_RbufSize()

SslLibGet_ReadStreaming Macro ^TOP^

Purpose

Determine whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_ReadStreaming (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

Returns a zero value if data is only returned when the full record has been downloaded, or a non-zero value otherwise.

See Also

"ReadStreaming," SslContextGet_ReadStreaming(), SslLibSet_ReadStreaming()

SslLibGet_VerifyCallback Macro ^TOP^

Purpose

Obtain a pointer to the callback function used to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_VerifyCallback (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

→ v

Pass the address of a pointer variable; upon return this variable will point to the callback function. The callback function is of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslLibSet_VerifyCallback(), SslContextGet_VerifyCallback()

SslLibGet_WbufSize Macro ^TOP^

Purpose

Obtain the size, in bytes, of the write buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibGet_WbufSize (
   refnum,
    lib
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib from which the value is to be retrieved.

Returns

The write buffer size. This is a value that ranges from 0 to 16384.

See Also

"WbufSize," SslLibSet_WbufSize(), SslContextGet_WbufSize()

SslLibSet_AppInt32 Macro ^TOP^

Purpose

Set the value of the AppInt32 attribute, an arbitrary 32-bit value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_AppInt32 (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

The 32-bit value.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppInt32," SslLibGet_AppInt32(), SslContextSet_AppInt32()

SslLibSet_AppPtr Macro ^TOP^

Purpose

Set the value of the AppPtr attribute, an arbitrary pointer value that an application can attach to an SslLib.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_AppPtr (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

The AppPtr attribute value.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslLibDestroy() does not modify this attribute, so if the data pointed to by this attribute needs to be disposed of, the application must do this itself.

See Also

"AppPtr," SslLibGet_AppPtr(), SslContextSet_AppPtr()

SslLibSet_AutoFlush Macro ^TOP^

Purpose

Specify whether SslSend() and SslWrite() should attempt to immediately send the supplied data bytes to the network.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_AutoFlush (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

Pass 0 to have the data buffered, or 1 to have the data sent immediately.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

It is very important to remember to use SslFlush() when AutoFlush is disabled.

See Also

"AutoFlush," SslContextGet_AutoFlush(), SslLibSet_AutoFlush()

SslLibSet_BufferedReuse Macro ^TOP^

Purpose

Specify whether the last message in an SslSession-reused handshake should be buffered instead of being sent over the network.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_BufferedReuse (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

Supply a value of 0 if the last message should not be buffered, or a non-zero value if it should.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"BufferedReuse," SslLibGet_BufferedReuse(), SslContextSet_BufferedReuse()

SslLibSet_CipherSuites Macro ^TOP^

Purpose

Specify the list of cipher suites that the SSL protocol should attempt to use. When an SslContext is created, it inherits this list of cipher suites.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_CipherSuites (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

Pointer to an array of byte pairs. The first two bytes contain the number of bytes that follow, and each successive pair is one of the values listed under "Cipher Suites."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"CipherSuites", SslLibGet_CipherSuites(), SslContextSet_CipherSuites()

SslLibSet_Compat Macro ^TOP^

Purpose

Determine how compatible the SSL protocol should be with certain incorrect SSL protocol implementations.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_Compat (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

The logical OR of those compatibility flags that correspond to the SSL protocol incompatibilities that should be accommodated. See "Compatibility Flags" for the defined constants that correspond to the compatibility flags.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"Compat," SslLibGet_Compat(), SslContextSet_Compat()

SslLibSet_DontSendShutdown Macro ^TOP^

Purpose

Specify whether or not an SslClose() should send a shutdown message to the server.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_DontSendShutdown (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

Zero if SslClose() should send a shutdown message, or a non-zero value if it shouldn't.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"DontSendShutdown," SslLibGet_DontSendShutdown(), SslContextSet_DontSendShutdown(), SslLibSet_DontWaitForShutdown()

SslLibSet_DontWaitForShutdown Macro ^TOP^

Purpose

Specify whether or not the SSlLib should wait for a shutdown message in SslClose().

Declared In

SslLibMac.h

Prototype

#define SslLibSet_DontWaitForShutdown (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

Zero if the SslLib waits for a shutdown message, or a non-zero value if it doesn't.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"DontWaitForShutdown," SslLibGet_DontWaitForShutdown(), SslLibSet_DontSendShutdown(), SslContextSet_DontWaitForShutdown()

SslLibSet_InfoCallback Macro ^TOP^

Purpose

Specify the callback function called when various situations occur during the usage of an SslLib. This callback is primarily intended for debugging and feedback purposes.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_InfoCallback (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

A pointer to a callback function of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "InfoCallback" and SslCallbackFunc() (documented) for more on how this callback function is used.

See Also

"InfoCallback," SslLibGet_InfoCallback(), SslContextSet_InfoCallback()

SslLibSet_InfoInterest Macro ^TOP^

Purpose

Specify the events for which the Info callback will be called.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_InfoInterest (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

The logical ORing of the sslFlgInfo... values listed under "InfoInterest Values."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"InfoInterest," SslLibGet_InfoInterest(), SslContextSet_InfoInterest()

SslLibSet_Mode Macro ^TOP^

Purpose

Specify the value of the Mode attribute, which controls whether the SSL protocol is on or off.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_Mode (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

One of the values listed under "Mode Attribute Values."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"Mode," SslLibGet_Mode(), SslContextSet_Mode()

SslLibSet_ProtocolVersion Macro ^TOP^

Purpose

Specify the version of the SSL protocol to use.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_ProtocolVersion (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

One of the values listed under "Protocol Versions."

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

SslLib implements only SSLv3 at this point in time, so modification of this value is not a good idea.

See Also

"ProtocolVersion," SslLibGet_ProtocolVersion(), SslContextSet_ProtocolVersion()

SslLibSet_RbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the read buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_RbufSize (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

The read buffer size. This is a value that ranges from 0 to 16384.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"RbufSize," SslLibGet_RbufSize(), SslContextSet_RbufSize()

SslLibSet_ReadStreaming Macro ^TOP^

Purpose

Specify whether data can be returned to the application from the SSL connection before the full record has been downloaded.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_ReadStreaming (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

A zero value if data is only to be returned when the full record has been downloaded, or a non-zero value otherwise.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"ReadStreaming," SslContextSet_ReadStreaming(), SslLibGet_ReadStreaming()

SslLibSet_VerifyCallback Macro ^TOP^

Purpose

Specify the callback function to assist with certificate verification.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_VerifyCallback (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

A pointer to a callback function of type SslCallbackFunc().

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

Comments

See "VerifyCallback" and SslCallbackFunc() (documented) for more on how this callback function is used to verify a certificate.

See Also

"VerifyCallback," SslLibGet_VerifyCallback(), SslContextSet_VerifyCallback()

SslLibSet_WbufSize Macro ^TOP^

Purpose

Specify the size, in bytes, of the write buffer. Read and write buffers are associated with an SslContext; SslContexts created against this SslLib will inherit the SslLib's buffer values.

Declared In

SslLibMac.h

Prototype

#define SslLibSet_WbufSize (
   refnum,
    lib,
    v
)

Parameters

→ refnum

SSL library reference number, obtained from a call to either SysLibFind() or SysLibLoad(), depending on whether or not the SSL library is already loaded.

→ lib

The SslLib on which to operate.

→ v

The write buffer size. This is a value that ranges from 0 to 16384.

Returns

Returns errNone if the operation completed successfully. Otherwise, the function that this macro evaluates to returns one of the error codes listed under "SSL Library Errors."

See Also

"WbufSize," SslLibGet_WbufSize(), SslContextSet_WbufSize()