1 /*
2  * Copyright (C) 2015 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.system;
18 
19 import static android.annotation.SystemApi.Client.MODULE_LIBRARIES;
20 
21 import android.annotation.SystemApi;
22 import android.compat.annotation.UnsupportedAppUsage;
23 
24 import java.net.SocketAddress;
25 import libcore.util.Objects;
26 
27 /**
28  * Netlink socket address.
29  *
30  * Corresponds to Linux's {@code struct sockaddr_nl} from
31  * <a href="https://github.com/torvalds/linux/blob/master/include/uapi/linux/netlink.h">&lt;linux/netlink.h&gt;</a>.
32  *
33  * Netlink socket address descirbes a netlink client is user space or in kernel.
34  * A {@link NetlinkSocketAddress} can be either unicast (only sent to one peer)
35  * or sent to netlink multicast groups ({@code nlGroupsMask} not equal 0).
36  *
37  * Any {@link NetlinkSocketAddress} is described by {@code nlPortId} and {@code nlGroupsMask}.
38  *
39  * {@code nlPortId} is the unicast address of netlink socket. It's always 0
40  * if the destination is in the kernel. For a user-space process,
41  * {@nlPortId} is usually the PID of the process owning the destination
42  * socket. However, {@nlPortId} identifies a netlink socket, not a
43  * process. If a process owns several netlink sockets, then {@nlPortId}
44  * can be equal to the process ID only for at most one socket.
45  *
46  * {@code nlGroupsMask} is a bit mask with every bit representing a netlink
47  * group number. The default value for this field is zero which means that
48  * no multicasts will be received. A socket may multicast messages to any
49  * of the multicast groups by setting {@code nlGroupsMask} to a bit mask of
50  * the groups it wishes to send to.
51  *
52  * @hide
53  */
54 @SystemApi(client = MODULE_LIBRARIES)
55 @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
56 public final class NetlinkSocketAddress extends SocketAddress {
57     /**
58      * port ID
59      *
60      * @hide
61      */
62     private final int nlPortId;
63 
64     /**
65      * multicast groups mask
66      *
67      * @hide
68      */
69     private final int nlGroupsMask;
70 
71     /**
72      * @hide
73      */
74     // VisibleForTesting
NetlinkSocketAddress()75     public NetlinkSocketAddress() {
76         this(0, 0);
77     }
78     /**
79      * @hide
80      */
81     // VisibleForTesting
NetlinkSocketAddress(int nlPortId)82     public NetlinkSocketAddress(int nlPortId) {
83         this(nlPortId, 0);
84     }
85 
86     /**
87      * Constructs an instance with the given port id and groups mask.
88      *
89      * @param nlPortId     port id
90      * @param nlGroupsMask groups mask
91      *
92      * @hide
93      */
94     @UnsupportedAppUsage
95     @SystemApi(client = MODULE_LIBRARIES)
96     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
NetlinkSocketAddress(int nlPortId, int nlGroupsMask)97     public NetlinkSocketAddress(int nlPortId, int nlGroupsMask) {
98         this.nlPortId = nlPortId;
99         this.nlGroupsMask = nlGroupsMask;
100     }
101 
102     /**
103      * Returns this address's port id.
104      *
105      * @return port id
106      *
107      * @hide
108      */
109     @SystemApi(client = MODULE_LIBRARIES)
110     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
getPortId()111     public int getPortId() {
112         return nlPortId;
113     }
114 
115     /**
116      * Returns this address's groups multicast mask.
117      *
118      * @return groups mask
119      *
120      * @hide
121      */
122     @SystemApi(client = MODULE_LIBRARIES)
123     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
getGroupsMask()124     public int getGroupsMask() {
125         return nlGroupsMask;
126     }
127 
128     /**
129      * @hide
130      */
toString()131     @Override public String toString() {
132       return Objects.toString(this);
133     }
134 }
135