Module org.newsclub.net.unix

Package org.newsclub.net.unix

Interface AFUNIXSocketExtensions

All Superinterfaces:

AFSocketExtensions

All Known Implementing Classes:

AFUNIXDatagramChannel, AFUNIXDatagramSocket, AFUNIXSocket, AFUNIXSocketChannel

public interface AFUNIXSocketExtensions
extends AFSocketExtensions

Defines certain methods that all junixsocket AF_UNIX socket implementations share and extend beyond the standard socket API. The set of features include methods to support working with ancillary messages (such as file descriptors) as well as socket credentials. Keep in mind that the platform this code runs on may not support these features, and exceptions may be thrown when not checking for the corresponding AFUNIXSocketCapability first.

Author:

Christian Kohlschütter

Method Summary

Modifier and Type	Method	Description
void	clearReceivedFileDescriptors()	Clears the queue of incoming FileDescriptors that were sent as ancillary messages.
AFUNIXSocketCredentials	getPeerCredentials()	Retrieves the "peer credentials" for this connection.
FileDescriptor[]	getReceivedFileDescriptors()	Retrieves an array of incoming FileDescriptors that were sent as ancillary messages, along with a call to InputStream.read(), etc.
boolean	hasOutboundFileDescriptors()	Returns true if there are pending file descriptors to be sent as part of an ancillary message.
void	setOutboundFileDescriptors(FileDescriptor... fdescs)	Sets a list of FileDescriptors that should be sent as an ancillary message along with the next write.

Methods inherited from interface org.newsclub.net.unix.AFSocketExtensions

ensureAncillaryReceiveBufferSize, getAncillaryReceiveBufferSize, setAncillaryReceiveBufferSize

Method Details

getReceivedFileDescriptors

FileDescriptor[] getReceivedFileDescriptors()
                                     throws IOException

Retrieves an array of incoming FileDescriptors that were sent as ancillary messages, along with a call to InputStream.read(), etc. NOTE: Another call to this method will not return the same file descriptors again (most likely, an empty array will be returned).

Returns:

The file descriptors, or an empty array if none were available.

Throws:

IOException - if the operation fails.

clearReceivedFileDescriptors

void clearReceivedFileDescriptors()

Clears the queue of incoming FileDescriptors that were sent as ancillary messages.

setOutboundFileDescriptors

void setOutboundFileDescriptors(FileDescriptor... fdescs)
                         throws IOException

Sets a list of FileDescriptors that should be sent as an ancillary message along with the next write. Important: There can only be one set of file descriptors active until the write completes. The socket also needs to be connected for this operation to succeed. It is also important to know that there may be an upper limit imposed by the operation system as to how many file descriptors can be sent at once. Linux, for example, may support up to 253. If the number of file descriptors exceeds the limit, an exception may be thrown when sending data along with the ancillary message containing the file descriptors.

Parameters:

fdescs - The file descriptors, or null if none.

Throws:

IOException - if the operation fails.

hasOutboundFileDescriptors

boolean hasOutboundFileDescriptors()

Returns true if there are pending file descriptors to be sent as part of an ancillary message.

Returns:

true if there are file descriptors pending.

getPeerCredentials

AFUNIXSocketCredentials getPeerCredentials()
                                    throws IOException

Retrieves the "peer credentials" for this connection. These credentials may be useful to authenticate the other end of the socket (client or server). Depending on the socket/connection/environment, you may not receive any or all credentials. For example, on Linux, AFUNIXDatagramSocket and AFUNIXDatagramChannel may not be able to retrieve credentials at all.

Returns:

The peer's credentials, or null if they couldn't be retrieved.

Throws:

IOException - If there was an error returning these credentials.