001/*
002 * Trident - A Multithreaded Server Alternative
003 * Copyright 2014 The TridentSDK Team
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package net.tridentsdk.server.netty.packet;
019
020import io.netty.buffer.ByteBuf;
021import net.tridentsdk.docs.InternalUseOnly;
022import net.tridentsdk.server.netty.ClientConnection;
023
024/**
025 * Data bearing abstraction that represents a piece of information to communicate between server and client
026 *
027 * @author The TridentSDK Team
028 */
029public interface Packet {
030    /**
031     * Sets the fields of the packet from the data serialized into the buffer
032     *
033     * @param buf the buffer storing the serialized packet data
034     * @return the this instance of the packet
035     */
036    Packet decode(ByteBuf buf);
037
038    /**
039     * Serialized the data held by this packet into a buffer
040     *
041     * @param buf the buffer to toPacket to
042     */
043    void encode(ByteBuf buf);
044
045    /**
046     * Handles the packet after receiving it from a connection, is invoked by the ClientConnection that received it
047     *
048     * <p>Used to allow the packet to notify the {@link net.tridentsdk.server.netty.ClientConnection}
049     * of packets the server receives, and make changes specific to this packet</p>
050     *
051     * @param connection The connection that sent the packet
052     */
053    @InternalUseOnly
054    void handleReceived(ClientConnection connection);
055
056    /**
057     * Gets the ID of this packet, according to the protocol specification
058     *
059     * @return packet ID
060     */
061    int id();
062
063    /**
064     * Returns the packet direction
065     *
066     * @return {@link net.tridentsdk.server.netty.packet.PacketDirection#IN} or
067     * {@link net.tridentsdk.server.netty.packet.PacketDirection#OUT} depending on direction
068     */
069    PacketDirection direction();
070}