Ethernet.h

00001 /* mbed Microcontroller Library - Ethernet
00002  * Copyright (c) 2009-2011 ARM Limited. All rights reserved.
00003  */ 
00004  
00005 #ifndef MBED_ETHERNET_H
00006 #define MBED_ETHERNET_H
00007 
00008 #include "device.h"
00009 
00010 #if DEVICE_ETHERNET
00011 
00012 #include "Base.h"
00013 
00014 namespace mbed {
00015 
00016 /** An ethernet interface, to use with the ethernet pins.
00017  *
00018  * Example:
00019  * @code
00020  * // Read destination and source from every ethernet packet
00021  * 
00022  * #include "mbed.h"
00023  * 
00024  * Ethernet eth;
00025  *  
00026  * int main() {
00027  *     char buf[0x600];
00028  *     
00029  *     while(1) {
00030  *         int size = eth.receive();
00031  *         if(size > 0) {
00032  *             eth.read(buf, size);
00033  *             printf("Destination:  %02X:%02X:%02X:%02X:%02X:%02X\n",
00034  *                     buf[0], buf[1], buf[2], buf[3], buf[4], buf[5]);
00035  *             printf("Source: %02X:%02X:%02X:%02X:%02X:%02X\n",
00036  *                     buf[6], buf[7], buf[8], buf[9], buf[10], buf[11]);
00037  *         }
00038  *         
00039  *         wait(1);
00040  *     }
00041  * }
00042  * @endcode
00043  */
00044 class Ethernet : public Base {
00045 
00046 public:
00047     
00048     /** Initialise the ethernet interface.
00049      */
00050     Ethernet();
00051 
00052     /** Powers the hardware down.
00053      */
00054     virtual ~Ethernet();
00055 
00056     enum Mode {
00057         AutoNegotiate
00058         , HalfDuplex10
00059         , FullDuplex10
00060         , HalfDuplex100
00061         , FullDuplex100
00062     };
00063 
00064     /** Writes into an outgoing ethernet packet.
00065      *
00066      *  It will append size bytes of data to the previously written bytes.
00067      *  
00068      *  @param data An array to write.
00069      *  @param size The size of data.
00070      *
00071      *  @returns
00072      *    The number of written bytes.
00073      */
00074     int write(const char *data, int size);
00075 
00076     /** Send an outgoing ethernet packet.
00077      *
00078      *  After filling in the data in an ethernet packet it must be send.
00079      *  Send will provide a new packet to write to.
00080      *
00081      *  @returns
00082      *    0 if the sending was failed,
00083      *    1 if the package is successfully sent.
00084      */
00085     int send();
00086 
00087     /** Recevies an arrived ethernet packet.
00088      *
00089      *  Receiving an ethernet packet will drop the last received ethernet packet 
00090      *  and make a new ethernet packet ready to read.
00091      *  If no ethernet packet is arrived it will return 0.
00092      *
00093      *  @returns
00094      *    0 if no ethernet packet is arrived,
00095      *    or the size of the arrived packet.
00096      */
00097     int receive();
00098 
00099     /** Read from an recevied ethernet packet.
00100      *
00101      *  After receive returnd a number bigger than 0it is
00102      *  possible to read bytes from this packet.
00103      *  Read will write up to size bytes into data.
00104      *
00105      *  It is possible to use read multible times. 
00106      *  Each time read will start reading after the last read byte before.
00107      *
00108      *  @returns
00109      *    The number of byte read.
00110      */
00111     int read(char *data, int size);
00112     
00113     /** Gives the ethernet address of the mbed.
00114      *
00115      *  @param mac Must be a pointer to a 6 byte char array to copy the ethernet address in.
00116      */
00117     void address(char *mac);
00118 
00119     /** Returns if an ethernet link is pressent or not. It takes a wile after Ethernet initializion to show up.
00120      * 
00121      *  @returns
00122      *   0 if no ethernet link is pressent,
00123      *   1 if an ethernet link is pressent.
00124      *
00125      * Example:
00126      * @code
00127      * // Using the Ethernet link function
00128      * #include "mbed.h"
00129      * 
00130      * Ethernet eth;
00131      * 
00132      * int main() {
00133      *     wait(1); // Needed after startup.
00134      *     if (eth.link()) {
00135      *          printf("online\n");
00136      *     } else {
00137      *          printf("offline\n");
00138      *     }
00139      * }
00140      * @endcode
00141      */
00142     int link();
00143 
00144     /** Sets the speed and duplex parameters of an ethernet link
00145      *
00146      * - AutoNegotiate      Auto negotiate speed and duplex
00147      * - HalfDuplex10       10 Mbit, half duplex
00148      * - FullDuplex10       10 Mbit, full duplex
00149      * - HalfDuplex100      100 Mbit, half duplex
00150      * - FullDuplex100      100 Mbit, full duplex
00151      *
00152      *  @param mode the speed and duplex mode to set the link to:
00153      */
00154     void set_link(Mode mode);
00155 
00156 };
00157 
00158 } // namespace mbed
00159 
00160 #endif
00161 
00162 #endif