1 /*
2 * junixsocket
3 *
4 * Copyright 2009-2024 Christian Kohlschütter
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.newsclub.net.unix;
19
20 import java.io.FileDescriptor;
21 import java.io.IOException;
22 import java.io.InputStream;
23
24 /**
25 * Defines certain methods that all junixsocket AF_UNIX socket implementations share and extend
26 * beyond the standard socket API.
27 *
28 * The set of features include methods to support working with ancillary messages (such as file
29 * descriptors) as well as socket credentials.
30 *
31 * Keep in mind that the platform this code runs on may not support these features, and exceptions
32 * may be thrown when not checking for the corresponding {@link AFUNIXSocketCapability} first.
33 *
34 * @author Christian Kohlschütter
35 */
36 public interface AFUNIXSocketExtensions extends AFSocketExtensions {
37 /**
38 * Retrieves an array of incoming {@link FileDescriptor}s that were sent as ancillary messages,
39 * along with a call to {@link InputStream#read()}, etc.
40 *
41 * NOTE: Another call to this method will not return the same file descriptors again (most likely,
42 * an empty array will be returned).
43 *
44 * @return The file descriptors, or an empty array if none were available.
45 * @throws IOException if the operation fails.
46 */
47 FileDescriptor[] getReceivedFileDescriptors() throws IOException;
48
49 /**
50 * Clears the queue of incoming {@link FileDescriptor}s that were sent as ancillary messages.
51 */
52 void clearReceivedFileDescriptors();
53
54 /**
55 * Sets a list of {@link FileDescriptor}s that should be sent as an ancillary message along with
56 * the next write.
57 *
58 * Important: There can only be one set of file descriptors active until the write completes. The
59 * socket also needs to be connected for this operation to succeed.
60 *
61 * It is also important to know that there may be an upper limit imposed by the operation system
62 * as to how many file descriptors can be sent at once. Linux, for example, may support up to 253.
63 * If the number of file descriptors exceeds the limit, an exception may be thrown when sending
64 * data along with the ancillary message containing the file descriptors.
65 *
66 * @param fdescs The file descriptors, or {@code null} if none.
67 * @throws IOException if the operation fails.
68 */
69 void setOutboundFileDescriptors(FileDescriptor... fdescs) throws IOException;
70
71 /**
72 * Returns {@code true} if there are pending file descriptors to be sent as part of an ancillary
73 * message.
74 *
75 * @return {@code true} if there are file descriptors pending.
76 */
77 boolean hasOutboundFileDescriptors();
78
79 /**
80 * Retrieves the "peer credentials" for this connection.
81 *
82 * These credentials may be useful to authenticate the other end of the socket (client or server).
83 *
84 * Depending on the socket/connection/environment, you may not receive any or all credentials. For
85 * example, on Linux, {@link AFUNIXDatagramSocket} and {@link AFUNIXDatagramChannel} may not be
86 * able to retrieve credentials at all.
87 *
88 * @return The peer's credentials, or {@code null} if they couldn't be retrieved.
89 * @throws IOException If there was an error returning these credentials.
90 */
91 AFUNIXSocketCredentials getPeerCredentials() throws IOException;
92 }