+ * Network connectors will check for this capability on blocks they are placed on. + * If found, they will actively poll frames via {@link #readEthernetFrame()} and push + * forwarded frames via {@link #writeEthernetFrame(NetworkInterface, byte[], int)}. + *
+ * As with all capabilities, this capability can be provided by {@link ItemDevice}s. + */ +public interface NetworkInterface { + /** + * Tries to read an ethernet frame from this network interface. + *
+ * The frame should be a Layer 2 Ethernet frame. + *
+ * When no data is available, {@code null} should be returned. + * + * @return a pending frame or {@code null}. + */ + @Nullable + byte[] readEthernetFrame(); + + /** + * Tries to write an ethernet frame to this network interface. + *
+ * The frame should be a Layer 2 Ethernet frame, but this is + * not guaranteed. Implementations should not rely on this, and if relying + * on this at least add appropriate validation and discard the frame otherwise. + *
+ * If the device is not ready to receive data, it may ignore the call. + *
+ * The {@code timeToLive} parameter is not to be confused with the IP protocol's + * TTL field. This parameter is used when pushing frames through the network bus + * to prevent infinite loops in case of cycles. Pure consumers can ignore this + * argument. Any implementation forwarding directly (by pushing it to some other + * {@link NetworkInterface} implementation) should call {@code writeEthernetFrame} + * with the time to live reduced by some value, usually by one. + * + * @param source the device that last forwarded the frame. + * @param frame the frame offered to the network interface. + * @param timeToLive the number of hops remaining before the frame should be discarded. + */ + void writeEthernetFrame(NetworkInterface source, byte[] frame, final int timeToLive); +} diff --git a/src/main/java/li/cil/oc2/api/capabilities/RedstoneEmitter.java b/src/main/java/li/cil/oc2/api/capabilities/RedstoneEmitter.java new file mode 100644 index 00000000..dea2be25 --- /dev/null +++ b/src/main/java/li/cil/oc2/api/capabilities/RedstoneEmitter.java @@ -0,0 +1,16 @@ +package li.cil.oc2.api.capabilities; + +/** + * This interface may be provided as a capability by item components to signal + * to the containing {@link net.minecraft.tileentity.TileEntity} that they wish + * to emit a redstone signal. This is used by the built-in redstone interface + * card, for example. + */ +public interface RedstoneEmitter { + /** + * Returns the redstone output level for the side this interface was returned for. + * + * @return the redstone output level. + */ + int getRedstoneOutput(); +} diff --git a/src/main/java/li/cil/oc2/api/capabilities/package-info.java b/src/main/java/li/cil/oc2/api/capabilities/package-info.java new file mode 100644 index 00000000..b242c41f --- /dev/null +++ b/src/main/java/li/cil/oc2/api/capabilities/package-info.java @@ -0,0 +1,7 @@ +@ParametersAreNonnullByDefault +@MethodsReturnNonnullByDefault +package li.cil.oc2.api.capabilities; + +import mcp.MethodsReturnNonnullByDefault; + +import javax.annotation.ParametersAreNonnullByDefault; \ No newline at end of file