tool/mbed/mbed-sdk/libraries/mbed/api/Ethernet.h

   1 /* mbed Microcontroller Library
   2  * Copyright (c) 2006-2013 ARM Limited
   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 #ifndef MBED_ETHERNET_H
  17 #define MBED_ETHERNET_H
  18
  19 #include "platform.h"
  20
  21 #if DEVICE_ETHERNET
  22
  23 namespace mbed {
  24
  25 /** An ethernet interface, to use with the ethernet pins.
  26  *
  27  * Example:
  28  * @code
  29  * // Read destination and source from every ethernet packet
  30  *
  31  * #include "mbed.h"
  32  *
  33  * Ethernet eth;
  34  *
  35  * int main() {
  36  *     char buf[0x600];
  37  *
  38  *     while(1) {
  39  *         int size = eth.receive();
  40  *         if(size > 0) {
  41  *             eth.read(buf, size);
  42  *             printf("Destination:  %02X:%02X:%02X:%02X:%02X:%02X\n",
  43  *                     buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
  44  *             printf("Source: %02X:%02X:%02X:%02X:%02X:%02X\n",
  45  *                     buf[6], buf[7], buf[8], buf[9], buf[10], buf[11]);
  46  *         }
  47  *
  48  *         wait(1);
  49  *     }
  50  * }
  51  * @endcode
  52  */
  53 class Ethernet {
  54
  55 public:
  56
  57     /** Initialise the ethernet interface.
  58      */
  59     Ethernet();
  60
  61     /** Powers the hardware down.
  62      */
  63     virtual ~Ethernet();
  64
  65     enum Mode {
  66         AutoNegotiate,
  67         HalfDuplex10,
  68         FullDuplex10,
  69         HalfDuplex100,
  70         FullDuplex100
  71     };
  72
  73     /** Writes into an outgoing ethernet packet.
  74      *
  75      *  It will append size bytes of data to the previously written bytes.
  76      *
  77      *  @param data An array to write.
  78      *  @param size The size of data.
  79      *
  80      *  @returns
  81      *   The number of written bytes.
  82      */
  83     int write(const char *data, int size);
  84
  85     /** Send an outgoing ethernet packet.
  86      *
  87      *  After filling in the data in an ethernet packet it must be send.
  88      *  Send will provide a new packet to write to.
  89      *
  90      *  @returns
  91      *    0 if the sending was failed,
  92      *    or the size of the packet successfully sent.
  93      */
  94     int send();
  95
  96     /** Recevies an arrived ethernet packet.
  97      *
  98      *  Receiving an ethernet packet will drop the last received ethernet packet
  99      *  and make a new ethernet packet ready to read.
 100      *  If no ethernet packet is arrived it will return 0.
 101      *
 102      *  @returns
 103      *    0 if no ethernet packet is arrived,
 104      *    or the size of the arrived packet.
 105      */
 106     int receive();
 107
 108     /** Read from an recevied ethernet packet.
 109      *
 110      *  After receive returnd a number bigger than 0it is
 111      *  possible to read bytes from this packet.
 112      *  Read will write up to size bytes into data.
 113      *
 114      *  It is possible to use read multible times.
 115      *  Each time read will start reading after the last read byte before.
 116      *
 117      *  @returns
 118      *  The number of byte read.
 119      */
 120     int read(char *data, int size);
 121
 122     /** Gives the ethernet address of the mbed.
 123      *
 124      *  @param mac Must be a pointer to a 6 byte char array to copy the ethernet address in.
 125      */
 126     void address(char *mac);
 127
 128     /** Returns if an ethernet link is pressent or not. It takes a wile after Ethernet initializion to show up.
 129      *
 130      *  @returns
 131      *   0 if no ethernet link is pressent,
 132      *   1 if an ethernet link is pressent.
 133      *
 134      * Example:
 135      * @code
 136      * // Using the Ethernet link function
 137      * #include "mbed.h"
 138      *
 139      * Ethernet eth;
 140      *
 141      * int main() {
 142      *     wait(1); // Needed after startup.
 143      *     if (eth.link()) {
 144      *          printf("online\n");
 145      *     } else {
 146      *          printf("offline\n");
 147      *     }
 148      * }
 149      * @endcode
 150      */
 151     int link();
 152
 153     /** Sets the speed and duplex parameters of an ethernet link
 154      *
 155      * - AutoNegotiate      Auto negotiate speed and duplex
 156      * - HalfDuplex10       10 Mbit, half duplex
 157      * - FullDuplex10       10 Mbit, full duplex
 158      * - HalfDuplex100      100 Mbit, half duplex
 159      * - FullDuplex100      100 Mbit, full duplex
 160      *
 161      *  @param mode the speed and duplex mode to set the link to:
 162      */
 163     void set_link(Mode mode);
 164 };
 165
 166 } // namespace mbed
 167
 168 #endif
 169
 170 #endif