diff --git a/src/main/java/li/cil/oc/api/Network.java b/src/main/java/li/cil/oc/api/Network.java
index ddc624746..e93e2d1a3 100644
--- a/src/main/java/li/cil/oc/api/Network.java
+++ b/src/main/java/li/cil/oc/api/Network.java
@@ -60,23 +60,70 @@ public final class Network {
instance.joinNewNetwork(node);
}
+ // ----------------------------------------------------------------------- //
+
+ /**
+ * Makes a wireless endpoint join the wireless network defined by the mod.
+ *
+ * OpenComputers tracks endpoints to which to send wireless packets sent
+ * via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)}
+ * method. The packets will only be sent to endpoints registered
+ * with the network.
+ *
+ * Important: when your endpoint is removed from the world,
+ * you must ensure it is also removed from the network!
+ *
+ * @param endpoint the endpoint to register with the network.
+ */
public static void joinWirelessNetwork(final WirelessEndpoint endpoint) {
if (instance != null)
instance.joinWirelessNetwork(endpoint);
}
+ /**
+ * Updates a wireless endpoint in the wireless network.
+ *
+ * This is more efficient than removing and then adding the node again, as
+ * it only performs the update if the position significantly changed since
+ * the last time the position was updated (more than 0.5 along any axis).
+ *
+ * Calling this for an endpoint that was not added before does nothing.
+ *
+ * @param endpoint the endpoint for which to update the position.
+ */
public static void updateWirelessNetwork(final WirelessEndpoint endpoint) {
if (instance != null)
instance.updateWirelessNetwork(endpoint);
}
+ /**
+ * Removes a wireless endpoint from the wireless network.
+ *
+ * This must be called when an endpoint becomes invalid, otherwise it will
+ * remain in the network!
+ *
+ * Calling this for an endpoint that was not added before does nothing.
+ *
+ * @param endpoint the endpoint to remove from the wireless network.
+ */
public static void leaveWirelessNetwork(final WirelessEndpoint endpoint) {
if (instance != null)
instance.leaveWirelessNetwork(endpoint);
}
- // ----------------------------------------------------------------------- //
-
+ /**
+ * Sends a packet via the wireless network.
+ *
+ * This will look for all other registered wireless endpoints in range of
+ * the sender and submit the packets to them. Whether another end point is
+ * reached depends on the distance and potential obstacles between the
+ * sender and the receiver (harder blocks require a stronger signal to be
+ * penetrated).
+ *
+ * @param source the endpoint that is sending the message.
+ * @param strength the signal strength with which to send the packet.
+ * @param packet the packet to send.
+ */
public static void sendWirelessPacket(final WirelessEndpoint source, final double strength, final Packet packet) {
if (instance != null)
instance.sendWirelessPacket(source, strength, packet);
@@ -127,12 +174,33 @@ public final class Network {
return null;
}
+ /**
+ * Creates a new network packet as it would be sent or received by a
+ * network card.
+ *
+ * These packets can be forwarded by switches and access points. For wired
+ * transmission they must be sent over a node's send method, with the
+ * message name being network.message.
+ *
+ * @param source the address of the sending node.
+ * @param destination the address of the destination, or null
+ * for a broadcast.
+ * @param port the port to send the packet to.
+ * @param data the payload of the packet.
+ * @return the new packet.
+ */
public static Packet newPacket(final String source, final String destination, final int port, final Object[] data) {
if (instance != null)
return instance.newPacket(source, destination, port, data);
return null;
}
+ /**
+ * Re-creates a network packet from a previously stored state.
+ *
+ * @param nbt the tag to load the packet from.
+ * @return the loaded packet.
+ */
public static Packet newPacket(final NBTTagCompound nbt) {
if (instance != null)
return instance.newPacket(nbt);
diff --git a/src/main/java/li/cil/oc/api/detail/NetworkAPI.java b/src/main/java/li/cil/oc/api/detail/NetworkAPI.java
index 5b497acfd..50f94567b 100644
--- a/src/main/java/li/cil/oc/api/detail/NetworkAPI.java
+++ b/src/main/java/li/cil/oc/api/detail/NetworkAPI.java
@@ -34,14 +34,61 @@ public interface NetworkAPI {
*/
void joinNewNetwork(Node node);
- void joinWirelessNetwork(WirelessEndpoint endpoint);
-
- void updateWirelessNetwork(WirelessEndpoint endpoint);
-
- void leaveWirelessNetwork(WirelessEndpoint endpoint);
-
// ----------------------------------------------------------------------- //
+ /**
+ * Makes a wireless endpoint join the wireless network defined by the mod.
+ *
+ * OpenComputers tracks endpoints to which to send wireless packets sent
+ * via the {@link #sendWirelessPacket(WirelessEndpoint, double, Packet)}
+ * method. The packets will only be sent to endpoints registered
+ * with the network.
+ *
+ * Important: when your endpoint is removed from the world,
+ * you must ensure it is also removed from the network!
+ *
+ * @param endpoint the endpoint to register with the network.
+ */
+ void joinWirelessNetwork(WirelessEndpoint endpoint);
+
+ /**
+ * Updates a wireless endpoint in the wireless network.
+ *
+ * This is more efficient than removing and then adding the node again, as
+ * it only performs the update if the position significantly changed since
+ * the last time the position was updated (more than 0.5 along any axis).
+ *
+ * Calling this for an endpoint that was not added before does nothing.
+ *
+ * @param endpoint the endpoint for which to update the position.
+ */
+ void updateWirelessNetwork(WirelessEndpoint endpoint);
+
+ /**
+ * Removes a wireless endpoint from the wireless network.
+ *
+ * This must be called when an endpoint becomes invalid, otherwise it will
+ * remain in the network!
+ *
+ * Calling this for an endpoint that was not added before does nothing.
+ *
+ * @param endpoint the endpoint to remove from the wireless network.
+ */
+ void leaveWirelessNetwork(WirelessEndpoint endpoint);
+
+ /**
+ * Sends a packet via the wireless network.
+ *
+ * This will look for all other registered wireless endpoints in range of
+ * the sender and submit the packets to them. Whether another end point is
+ * reached depends on the distance and potential obstacles between the
+ * sender and the receiver (harder blocks require a stronger signal to be
+ * penetrated).
+ *
+ * @param source the endpoint that is sending the message.
+ * @param strength the signal strength with which to send the packet.
+ * @param packet the packet to send.
+ */
void sendWirelessPacket(WirelessEndpoint source, double strength, Packet packet);
// ----------------------------------------------------------------------- //
@@ -85,7 +132,28 @@ public interface NetworkAPI {
*/
Builder.NodeBuilder newNode(Environment host, Visibility reachability);
+ /**
+ * Creates a new network packet as it would be sent or received by a
+ * network card.
+ *
+ * These packets can be forwarded by switches and access points. For wired
+ * transmission they must be sent over a node's send method, with the
+ * message name being network.message.
+ *
+ * @param source the address of the sending node.
+ * @param destination the address of the destination, or null
+ * for a broadcast.
+ * @param port the port to send the packet to.
+ * @param data the payload of the packet.
+ * @return the new packet.
+ */
Packet newPacket(String source, String destination, int port, Object[] data);
+ /**
+ * Re-creates a network packet from a previously stored state.
+ *
+ * @param nbt the tag to load the packet from.
+ * @return the loaded packet.
+ */
Packet newPacket(NBTTagCompound nbt);
}
\ No newline at end of file
diff --git a/src/main/java/li/cil/oc/api/network/WirelessEndpoint.java b/src/main/java/li/cil/oc/api/network/WirelessEndpoint.java
index 4bf146626..df262ffef 100644
--- a/src/main/java/li/cil/oc/api/network/WirelessEndpoint.java
+++ b/src/main/java/li/cil/oc/api/network/WirelessEndpoint.java
@@ -6,6 +6,12 @@ import net.minecraft.world.World;
* Interface for wireless endpoints that can be registered with the internal
* wireless network registry.
*
+ * These can be added to the wireless network via the Network API, to
+ * allow them to receive packets like wireless network cards and access points
+ * do (and handle or forward them as they see fit).
+ *
+ * If the position of the endpoint can change, it must be updated manually via
+ * {@link li.cil.oc.api.Network#updateWirelessNetwork(WirelessEndpoint)}.
*/
public interface WirelessEndpoint {
/**
diff --git a/src/main/java/li/cil/oc/api/package-info.java b/src/main/java/li/cil/oc/api/package-info.java
index 2b86ad759..974733598 100644
--- a/src/main/java/li/cil/oc/api/package-info.java
+++ b/src/main/java/li/cil/oc/api/package-info.java
@@ -37,5 +37,5 @@
@cpw.mods.fml.common.API(
owner = "OpenComputers|Core",
provides = "OpenComputersAPI",
- apiVersion = "1.4.7")
+ apiVersion = "1.4.8")
package li.cil.oc.api;
\ No newline at end of file