From d048748002747edf5aa1b9ae955f2327153babfe Mon Sep 17 00:00:00 2001 From: Guenter Obiltschnig Date: Sun, 30 Jan 2011 10:37:19 +0000 Subject: [PATCH] see changelog --- CHANGELOG | 7 +- Foundation/src/URI.cpp | 10 +- Net/include/Poco/Net/MediaType.h | 23 ++- Net/include/Poco/Net/NetException.h | 3 +- Net/src/MediaType.cpp | 24 ++- Net/src/NetException.cpp | 3 +- Net/src/Socket.cpp | 32 +-- Net/src/SocketImpl.cpp | 49 ++--- Net/testsuite/src/MediaTypeTest.cpp | 35 +++- Net/testsuite/src/MediaTypeTest.h | 3 +- README | 11 +- doc/00100-GuidedTour.page | 2 +- doc/00200-GettingStarted.page | 301 ++++++++++++++++++++++++++++ doc/99100-ReleaseNotes.page | 5 + 14 files changed, 461 insertions(+), 47 deletions(-) create mode 100644 doc/00200-GettingStarted.page diff --git a/CHANGELOG b/CHANGELOG index 28273c342..527ee997d 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -47,6 +47,11 @@ Release 1.4.1 (2011-01-29) for the samDesired argument of RegOpenKeyEx() or RegCreateKeyEx(). - improved Poco::BasicEvent::notify() performance by avoiding an unnecessary heap allocation. +- added additional well-known port numbers to Poco::URI: rtsp, sip, sips, xmpp. +- added Poco::Net::MediaType::matchesRange() +- improved invalid socket handling: a Poco::Net::InvalidSocketException is + now thrown instead of an assertion when an operation is attempted on a closed or + otherwise uninitialized socket. Release 1.4.0 (2010-12-14) @@ -1454,4 +1459,4 @@ building the libraries. -- -$Id: //poco/1.4/dist/CHANGELOG#10 $ +$Id: //poco/1.4/dist/CHANGELOG#12 $ diff --git a/Foundation/src/URI.cpp b/Foundation/src/URI.cpp index 6a5273463..037bb2583 100644 --- a/Foundation/src/URI.cpp +++ b/Foundation/src/URI.cpp @@ -1,7 +1,7 @@ // // URI.cpp // -// $Id: //poco/1.4/Foundation/src/URI.cpp#1 $ +// $Id: //poco/1.4/Foundation/src/URI.cpp#2 $ // // Library: Foundation // Package: URI @@ -647,6 +647,14 @@ unsigned short URI::getWellKnownPort() const return 389; else if (_scheme == "https") return 443; + else if (_scheme == "rtsp") + return 554; + else if (_scheme == "sip") + return 5060; + else if (_scheme == "sips") + return 5061; + else if (_scheme == "xmpp") + return 5222; else return 0; } diff --git a/Net/include/Poco/Net/MediaType.h b/Net/include/Poco/Net/MediaType.h index 5267bb5ae..ad834c9f9 100644 --- a/Net/include/Poco/Net/MediaType.h +++ b/Net/include/Poco/Net/MediaType.h @@ -1,7 +1,7 @@ // // MediaType.h // -// $Id: //poco/1.4/Net/include/Poco/Net/MediaType.h#1 $ +// $Id: //poco/1.4/Net/include/Poco/Net/MediaType.h#2 $ // // Library: Net // Package: Messages @@ -125,6 +125,27 @@ public: /// Returns true iff the type matches the given type. /// Matching is case insensitive. + bool matchesRange(const MediaType& mediaType) const; + /// Returns true if the type and subtype match + /// the type and subtype of the given media type. + /// If the MIME type is a range of types it matches + /// any media type withing the range (e.g. "image/*" matches + /// any image media type, "*/*" matches anything). + /// Matching is case insensitive. + + bool matchesRange(const std::string& type, const std::string& subType) const; + /// Returns true if the type and subtype match + /// the given type and subtype. + /// If the MIME type is a range of types it matches + /// any media type withing the range (e.g. "image/*" matches + /// any image media type, "*/*" matches anything). + /// Matching is case insensitive. + + bool matchesRange(const std::string& type) const; + /// Returns true if the type matches the given type or + /// the type is a range of types denoted by "*". + /// Matching is case insensitive. + protected: void parse(const std::string& mediaType); diff --git a/Net/include/Poco/Net/NetException.h b/Net/include/Poco/Net/NetException.h index 14c50f7e7..f8d0c9e6f 100644 --- a/Net/include/Poco/Net/NetException.h +++ b/Net/include/Poco/Net/NetException.h @@ -1,7 +1,7 @@ // // NetException.h // -// $Id: //poco/1.4/Net/include/Poco/Net/NetException.h#1 $ +// $Id: //poco/1.4/Net/include/Poco/Net/NetException.h#2 $ // // Library: Net // Package: NetCore @@ -50,6 +50,7 @@ namespace Net { POCO_DECLARE_EXCEPTION(Net_API, NetException, Poco::IOException) POCO_DECLARE_EXCEPTION(Net_API, InvalidAddressException, NetException) +POCO_DECLARE_EXCEPTION(Net_API, InvalidSocketException, NetException) POCO_DECLARE_EXCEPTION(Net_API, ServiceNotFoundException, NetException) POCO_DECLARE_EXCEPTION(Net_API, ConnectionAbortedException, NetException) POCO_DECLARE_EXCEPTION(Net_API, ConnectionResetException, NetException) diff --git a/Net/src/MediaType.cpp b/Net/src/MediaType.cpp index 4bebbbe58..cc1a2ee42 100644 --- a/Net/src/MediaType.cpp +++ b/Net/src/MediaType.cpp @@ -1,7 +1,7 @@ // // MediaType.cpp // -// $Id: //poco/1.4/Net/src/MediaType.cpp#1 $ +// $Id: //poco/1.4/Net/src/MediaType.cpp#2 $ // // Library: Net // Package: Messages @@ -172,6 +172,28 @@ bool MediaType::matches(const std::string& type) const } +bool MediaType::matchesRange(const MediaType& mediaType) const +{ + return matchesRange(mediaType._type, mediaType._subType); +} + + +bool MediaType::matchesRange(const std::string& type, const std::string& subType) const +{ + if (_type == "*" || type == "*" || icompare(_type, type) == 0) + { + return _subType == "*" || subType == "*" || icompare(_subType, subType) == 0; + } + else return false; +} + + +bool MediaType::matchesRange(const std::string& type) const +{ + return _type == "*" || type == "*" || matches(type); +} + + void MediaType::parse(const std::string& mediaType) { _type.clear(); diff --git a/Net/src/NetException.cpp b/Net/src/NetException.cpp index e8b16a958..4509e78a8 100644 --- a/Net/src/NetException.cpp +++ b/Net/src/NetException.cpp @@ -1,7 +1,7 @@ // // NetException.cpp // -// $Id: //poco/1.4/Net/src/NetException.cpp#1 $ +// $Id: //poco/1.4/Net/src/NetException.cpp#2 $ // // Library: Net // Package: NetCore @@ -47,6 +47,7 @@ namespace Net { POCO_IMPLEMENT_EXCEPTION(NetException, IOException, "Net Exception") POCO_IMPLEMENT_EXCEPTION(InvalidAddressException, NetException, "Invalid address") +POCO_IMPLEMENT_EXCEPTION(InvalidSocketException, NetException, "Invalid socket") POCO_IMPLEMENT_EXCEPTION(ServiceNotFoundException, NetException, "Service not found") POCO_IMPLEMENT_EXCEPTION(ConnectionAbortedException, NetException, "Software caused connection abort") POCO_IMPLEMENT_EXCEPTION(ConnectionResetException, NetException, "Connection reset by peer") diff --git a/Net/src/Socket.cpp b/Net/src/Socket.cpp index b7300afad..900f0ebcb 100644 --- a/Net/src/Socket.cpp +++ b/Net/src/Socket.cpp @@ -1,7 +1,7 @@ // // Socket.cpp // -// $Id: //poco/1.4/Net/src/Socket.cpp#1 $ +// $Id: //poco/1.4/Net/src/Socket.cpp#2 $ // // Library: Net // Package: Sockets @@ -102,12 +102,13 @@ int Socket::select(SocketList& readList, SocketList& writeList, SocketList& exce struct epoll_event* eventLast = eventsIn; for (SocketList::iterator it = readList.begin(); it != readList.end(); ++it) { - if (it->sockfd() != POCO_INVALID_SOCKET) + poco_socket_t sockfd = it->sockfd(); + if (sockfd != POCO_INVALID_SOCKET) { struct epoll_event* e = eventsIn; for (; e != eventLast; ++e) { - if (reinterpret_cast (e->data.ptr)->sockfd() == it->sockfd()) + if (reinterpret_cast(e->data.ptr)->sockfd() == sockfd) break; } if (e == eventLast) @@ -121,12 +122,13 @@ int Socket::select(SocketList& readList, SocketList& writeList, SocketList& exce for (SocketList::iterator it = writeList.begin(); it != writeList.end(); ++it) { - if (it->sockfd() != POCO_INVALID_SOCKET) + poco_socket_t sockfd = it->sockfd(); + if (sockfd != POCO_INVALID_SOCKET) { struct epoll_event* e = eventsIn; for (; e != eventLast; ++e) { - if (reinterpret_cast (e->data.ptr)->sockfd() == it->sockfd()) + if (reinterpret_cast(e->data.ptr)->sockfd() == sockfd) break; } if (e == eventLast) @@ -140,12 +142,13 @@ int Socket::select(SocketList& readList, SocketList& writeList, SocketList& exce for (SocketList::iterator it = exceptList.begin(); it != exceptList.end(); ++it) { - if (it->sockfd() != POCO_INVALID_SOCKET) + poco_socket_t sockfd = it->sockfd(); + if (sockfd != POCO_INVALID_SOCKET) { struct epoll_event* e = eventsIn; for (; e != eventLast; ++e) { - if (reinterpret_cast (e->data.ptr)->sockfd() == it->sockfd()) + if (reinterpret_cast(e->data.ptr)->sockfd() == sockfd) break; } if (e == eventLast) @@ -163,18 +166,21 @@ int Socket::select(SocketList& readList, SocketList& writeList, SocketList& exce { char buf[1024]; strerror_r(errno, buf, sizeof(buf)); - SocketImpl::error(std::string("Can't create epoll queue: ") + buf); } for (struct epoll_event* e = eventsIn; e != eventLast; ++e) { - if (epoll_ctl(epollfd, EPOLL_CTL_ADD, reinterpret_cast (e->data.ptr)->sockfd(), e) < 0) + poco_socket_t sockfd = reinterpret_cast(e->data.ptr)->sockfd(); + if (sockfd != POCO_INVALID_SOCKET) { - char buf[1024]; - strerror_r(errno, buf, sizeof(buf)); - ::close(epollfd); - SocketImpl::error(std::string("Can't insert socket to epoll queue: ") + buf); + if (epoll_ctl(epollfd, EPOLL_CTL_ADD, sockfd, e) < 0) + { + char buf[1024]; + strerror_r(errno, buf, sizeof(buf)); + ::close(epollfd); + SocketImpl::error(std::string("Can't insert socket to epoll queue: ") + buf); + } } } } diff --git a/Net/src/SocketImpl.cpp b/Net/src/SocketImpl.cpp index 1f551002a..bba8df4a7 100644 --- a/Net/src/SocketImpl.cpp +++ b/Net/src/SocketImpl.cpp @@ -1,7 +1,7 @@ // // SocketImpl.cpp // -// $Id: //poco/1.4/Net/src/SocketImpl.cpp#2 $ +// $Id: //poco/1.4/Net/src/SocketImpl.cpp#3 $ // // Library: Net // Package: Sockets @@ -78,7 +78,7 @@ SocketImpl::~SocketImpl() SocketImpl* SocketImpl::acceptConnection(SocketAddress& clientAddr) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); char buffer[SocketAddress::MAX_ADDRESS_LENGTH]; struct sockaddr* pSA = reinterpret_cast(buffer); @@ -200,7 +200,7 @@ void SocketImpl::bind(const SocketAddress& address, bool reuseAddress) void SocketImpl::listen(int backlog) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); int rc = ::listen(_sockfd, backlog); if (rc != 0) error(); @@ -219,7 +219,7 @@ void SocketImpl::close() void SocketImpl::shutdownReceive() { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); int rc = ::shutdown(_sockfd, 0); if (rc != 0) error(); @@ -228,7 +228,7 @@ void SocketImpl::shutdownReceive() void SocketImpl::shutdownSend() { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); int rc = ::shutdown(_sockfd, 1); if (rc != 0) error(); @@ -237,7 +237,7 @@ void SocketImpl::shutdownSend() void SocketImpl::shutdown() { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); int rc = ::shutdown(_sockfd, 2); if (rc != 0) error(); @@ -246,8 +246,6 @@ void SocketImpl::shutdown() int SocketImpl::sendBytes(const void* buffer, int length, int flags) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); - #if defined(POCO_BROKEN_TIMEOUTS) if (_sndTimeout.totalMicroseconds() != 0) { @@ -259,6 +257,7 @@ int SocketImpl::sendBytes(const void* buffer, int length, int flags) int rc; do { + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); rc = ::send(_sockfd, reinterpret_cast(buffer), length, flags); } while (rc < 0 && lastError() == POCO_EINTR); @@ -269,8 +268,6 @@ int SocketImpl::sendBytes(const void* buffer, int length, int flags) int SocketImpl::receiveBytes(void* buffer, int length, int flags) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); - #if defined(POCO_BROKEN_TIMEOUTS) if (_recvTimeout.totalMicroseconds() != 0) { @@ -278,10 +275,11 @@ int SocketImpl::receiveBytes(void* buffer, int length, int flags) throw TimeoutException(); } #endif - + int rc; do { + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); rc = ::recv(_sockfd, reinterpret_cast(buffer), length, flags); } while (rc < 0 && lastError() == POCO_EINTR); @@ -299,11 +297,10 @@ int SocketImpl::receiveBytes(void* buffer, int length, int flags) int SocketImpl::sendTo(const void* buffer, int length, const SocketAddress& address, int flags) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); - int rc; do { + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); #if defined(POCO_VXWORKS) rc = ::sendto(_sockfd, (char*) buffer, length, flags, (sockaddr*) address.addr(), address.length()); #else @@ -318,8 +315,6 @@ int SocketImpl::sendTo(const void* buffer, int length, const SocketAddress& addr int SocketImpl::receiveFrom(void* buffer, int length, SocketAddress& address, int flags) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); - #if defined(POCO_BROKEN_TIMEOUTS) if (_recvTimeout.totalMicroseconds() != 0) { @@ -334,6 +329,7 @@ int SocketImpl::receiveFrom(void* buffer, int length, SocketAddress& address, in int rc; do { + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); rc = ::recvfrom(_sockfd, reinterpret_cast(buffer), length, flags, pSA, &saLen); } while (rc < 0 && lastError() == POCO_EINTR); @@ -355,6 +351,8 @@ int SocketImpl::receiveFrom(void* buffer, int length, SocketAddress& address, in void SocketImpl::sendUrgent(unsigned char data) { + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); + int rc = ::send(_sockfd, reinterpret_cast(&data), sizeof(data), MSG_OOB); if (rc < 0) error(); } @@ -376,6 +374,9 @@ bool SocketImpl::secure() const bool SocketImpl::poll(const Poco::Timespan& timeout, int mode) { + poco_socket_t sockfd = _sockfd; + if (sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); + #if defined(POCO_HAVE_FD_EPOLL) int epollfd = epoll_create(1); @@ -396,7 +397,7 @@ bool SocketImpl::poll(const Poco::Timespan& timeout, int mode) if (mode & SELECT_ERROR) evin.events |= EPOLLERR; - if (epoll_ctl(epollfd, EPOLL_CTL_ADD, _sockfd, &evin) < 0) + if (epoll_ctl(epollfd, EPOLL_CTL_ADD, sockfd, &evin) < 0) { char buf[1024]; strerror_r(errno, buf, sizeof(buf)); @@ -439,15 +440,15 @@ bool SocketImpl::poll(const Poco::Timespan& timeout, int mode) FD_ZERO(&fdExcept); if (mode & SELECT_READ) { - FD_SET(_sockfd, &fdRead); + FD_SET(sockfd, &fdRead); } if (mode & SELECT_WRITE) { - FD_SET(_sockfd, &fdWrite); + FD_SET(sockfd, &fdWrite); } if (mode & SELECT_ERROR) { - FD_SET(_sockfd, &fdExcept); + FD_SET(sockfd, &fdExcept); } Poco::Timespan remainingTime(timeout); int rc; @@ -457,7 +458,7 @@ bool SocketImpl::poll(const Poco::Timespan& timeout, int mode) tv.tv_sec = (long) remainingTime.totalSeconds(); tv.tv_usec = (long) remainingTime.useconds(); Poco::Timestamp start; - rc = ::select(int(_sockfd) + 1, &fdRead, &fdWrite, &fdExcept, &tv); + rc = ::select(int(sockfd) + 1, &fdRead, &fdWrite, &fdExcept, &tv); if (rc < 0 && lastError() == POCO_EINTR) { Poco::Timestamp end; @@ -566,7 +567,7 @@ Poco::Timespan SocketImpl::getReceiveTimeout() SocketAddress SocketImpl::address() { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); char buffer[SocketAddress::MAX_ADDRESS_LENGTH]; struct sockaddr* pSA = reinterpret_cast(buffer); @@ -582,7 +583,7 @@ SocketAddress SocketImpl::address() SocketAddress SocketImpl::peerAddress() { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); char buffer[SocketAddress::MAX_ADDRESS_LENGTH]; struct sockaddr* pSA = reinterpret_cast(buffer); @@ -632,7 +633,7 @@ void SocketImpl::setOption(int level, int option, const Poco::Timespan& value) void SocketImpl::setRawOption(int level, int option, const void* value, poco_socklen_t length) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); #if defined(POCO_VXWORKS) int rc = ::setsockopt(_sockfd, level, option, (char*) value, length); @@ -684,7 +685,7 @@ void SocketImpl::getOption(int level, int option, IPAddress& value) void SocketImpl::getRawOption(int level, int option, void* value, poco_socklen_t& length) { - poco_assert (_sockfd != POCO_INVALID_SOCKET); + if (_sockfd == POCO_INVALID_SOCKET) throw InvalidSocketException(); int rc = ::getsockopt(_sockfd, level, option, reinterpret_cast(value), &length); if (rc == -1) error(); diff --git a/Net/testsuite/src/MediaTypeTest.cpp b/Net/testsuite/src/MediaTypeTest.cpp index e7c7a1dfa..9e7ae9c51 100644 --- a/Net/testsuite/src/MediaTypeTest.cpp +++ b/Net/testsuite/src/MediaTypeTest.cpp @@ -1,7 +1,7 @@ // // MediaTypeTest.cpp // -// $Id: //poco/1.4/Net/testsuite/src/MediaTypeTest.cpp#1 $ +// $Id: //poco/1.4/Net/testsuite/src/MediaTypeTest.cpp#2 $ // // Copyright (c) 2005-2006, Applied Informatics Software Engineering GmbH. // and Contributors. @@ -99,6 +99,38 @@ void MediaTypeTest::testMatch() } +void MediaTypeTest::testMatchRange() +{ + MediaType mt1("Text/Plain"); + MediaType mt2("text/plain"); + MediaType mt3("text/xml"); + MediaType mt4("image/jpg"); + MediaType mt5("text/*"); + MediaType mt6("*/*"); + assert (mt1.matchesRange(mt5)); + assert (mt2.matchesRange(mt5)); + assert (mt3.matchesRange(mt5)); + assert (!mt4.matchesRange(mt5)); + assert (mt1.matchesRange(mt6)); + assert (mt2.matchesRange(mt6)); + assert (mt3.matchesRange(mt6)); + assert (mt4.matchesRange(mt6)); + + assert (mt5.matchesRange(mt1)); + assert (mt5.matchesRange(mt2)); + assert (mt5.matchesRange(mt3)); + assert (!mt5.matchesRange(mt4)); + + assert (mt1.matchesRange("text", "*")); + assert (mt2.matchesRange("text", "*")); + assert (mt3.matchesRange("text", "*")); + assert (!mt4.matchesRange("text", "*")); + + assert (mt1.matchesRange("*")); + assert (mt4.matchesRange("*")); +} + + void MediaTypeTest::setUp() { } @@ -116,6 +148,7 @@ CppUnit::Test* MediaTypeTest::suite() CppUnit_addTest(pSuite, MediaTypeTest, testParse); CppUnit_addTest(pSuite, MediaTypeTest, testToString); CppUnit_addTest(pSuite, MediaTypeTest, testMatch); + CppUnit_addTest(pSuite, MediaTypeTest, testMatchRange); return pSuite; } diff --git a/Net/testsuite/src/MediaTypeTest.h b/Net/testsuite/src/MediaTypeTest.h index 8591636ab..5bb261c78 100644 --- a/Net/testsuite/src/MediaTypeTest.h +++ b/Net/testsuite/src/MediaTypeTest.h @@ -1,7 +1,7 @@ // // MediaTypeTest.h // -// $Id: //poco/1.4/Net/testsuite/src/MediaTypeTest.h#1 $ +// $Id: //poco/1.4/Net/testsuite/src/MediaTypeTest.h#2 $ // // Definition of the MediaTypeTest class. // @@ -49,6 +49,7 @@ public: void testParse(); void testToString(); void testMatch(); + void testMatchRange(); void setUp(); void tearDown(); diff --git a/README b/README index 84dafd340..2be8d7bdd 100644 --- a/README +++ b/README @@ -21,6 +21,7 @@ build/ the build system for Unix/OpenVMS and additional util rules/ common build rules for all platforms scripts/ build and utility scripts vms/ OpenVMS build system scripts + vxconfig/ VxWorks build configurations bin/ all executables (dynamic link libraries on Windows) bin64/ all 64-bit executables (and DLLs) @@ -243,6 +244,14 @@ available: > ./configure --omit=NetSSL_OpenSSL,Crypto,Data/ODBC,Data/MySQL +BUILDING FOR VXWORKS +==================== + +Please see the VxWorks Platform Notes in the Reference Documentation for +more information. The Reference Documentation can be found online +at . + + BUILDING ON OPENVMS =================== @@ -282,4 +291,4 @@ at . -- -$Id: //poco/1.4/dist/README#2 $ +$Id: //poco/1.4/dist/README#3 $ diff --git a/doc/00100-GuidedTour.page b/doc/00100-GuidedTour.page index ffbb4752f..81b99d9a5 100644 --- a/doc/00100-GuidedTour.page +++ b/doc/00100-GuidedTour.page @@ -1,4 +1,4 @@ -A Guided Tour of the POCO C++ Libraries +A Guided Tour Of The POCO C++ Libraries AAAIntroduction !!! Introduction diff --git a/doc/00200-GettingStarted.page b/doc/00200-GettingStarted.page new file mode 100644 index 000000000..9c6838de6 --- /dev/null +++ b/doc/00200-GettingStarted.page @@ -0,0 +1,301 @@ +Getting Started With The POCO C++ Libraries +AAAIntroduction + +!!!Welcome + +Thank you for downloading the POCO C++ Libraries and welcome to the growing community of POCO C++ Libraries +users. This document will help you in getting a smooth ride while installing and setting up the +POCO C++ Libraries and going the first steps with the software. + + +!!!Setting Up The POCO C++ Libraries + +The POCO C++ Libraries are delivered in full source code only. Due to the +large number of possible build configurations, no binary releases are provided +from the project maintainers. +This means that you have to build the libraries and tools before you can use them the first time. + +<*Note: There are binary releases available as installation packages for +various operating systems (e.g., Debian Linux, Ubuntu Linux, OpenBSD, +OpenWRT, etc.). However, these packages are not maintained by the core +team and may not always be up to date.*> + + +!!Source Code Distribution Format + +The source code for the POCO C++ Libraries is delivered in a ZIP file +for Windows users and/or in a compressed TAR file (.tar.gz or .tar.bz2) +for Unix/Linux users. Both archives contain the same files, the only +difference is that all text files in the ZIP files have line endings +suitable for Windows (CR-LF), while the text files in the TAR file have +line endings suitable for Unix/Linux (LF only). +All libraries and tools follow a common convention for the directory +layout. This directory layout is shown below. + + build/ the build system for Unix/OpenVMS and additional utility scripts + config/ build configurations for various Unix platforms + rules/ common build rules for all platforms + scripts/ build and utility scripts + vms/ OpenVMS build system scripts + vxconfig/ VxWorks build configurations + + bin/ all executables (dynamic link libraries on Windows) + bin64/ all 64-bit executables (and DLLs) + + doc/ additional documentation + + lib/ all libraries (import libraries on Windows) + lib64/ all 64-bit libraries + + CppUnit/ project and make/build files for the CppUnit unit testing framework + doc/ additional documentation + include/ + CppUnit/ header files for CppUnit + src/ source files for CppUnit + WinTestRunner/ Windows GUI for CppUnit + + Foundation/ project and make/build files for the Foundation library + include/ + Poco/ header files for the Foundation library + src/ source files for the Foundation library + testsuite/ project and make/build files for the Foundation testsuite + src/ source files for the Foundation testsuite + bin/ test suite executables + samples/ sample applications for the Foundation library + + XML/ project and make/build files for the XML library + include/ + Poco/ + XML/ header files for the core XML library + SAX/ header files for SAX support + DOM/ header files for DOM support + src/ source files for the XML library + testsuite/ project and make/build files for the XML testsuite + src/ source files for the XML testsuite + bin/ test suite executables + samples/ sample applications for the XML library + + Net/ project and make/build files for the Net library + include/ + Poco/ + Net/ header files for the Net library + src/ source files for the Net library + testsuite/ project and make/build files for the Net testsuite + src/ source files for the Net testsuite + bin/ test suite executables + samples/ sample applications for the Net library +---- + +Depending on what package you have downloaded (Basic or Complete +Edition), there may be other libraries as well (such as Data, Crypto, +NetSSL_OpenSSL and Zip). + + +!!External Dependencies + +The following libraries require third-party software (header files and +libraries) being installed to build properly: + + - NetSSL_OpenSSL and Crypt require OpenSSL. + - Data/ODBC requires ODBC + (Microsoft ODBC on Windows, unixODBC or iODBC on Unix/Linux) + - Data/MySQL requires the MySQL client. + + +!OpenSSL + +Most Unix/Linux systems (including Mac OS X) already have OpenSSL +preinstalled, or OpenSSL can be easily installed using the system’s +package management facility. For example, on Ubuntu (or other +Debian-based Linux distributions) you can type + + $ sudo apt-get install openssl libssl-dev +---- + +to install the necessary packages. +If your system does not have OpenSSL, please get it from +http://www.openssl.org/ or another source. You do not have to build +OpenSSL yourself -- a binary distribution is fine. + +The easiest way to install OpenSSL on Windows is to use a binary +(prebuild) release, for example the one from Shining Light +Productions that comes with a Windows installer +(http://www.slproweb.com/products/Win32OpenSSL.html). +Depending on where you have installed the OpenSSL libraries, +you might have to edit the build script (buildwin.cmd), or add the +necessary paths to the INCLUDE and LIB environment variables. You might also +have to edit the project settings if the names of the OpenSSL libraries +from your build differ from the names used in the project files. + + +!ODBC + +The Data library requires ODBC support on your system if you want to +build the ODBC connector (which is the default). On Windows platforms, +ODBC should be readily available if you have the Windows SDK installed. +On Unix/Linux platforms, you can use [[http://www.iodbc.org/ iODBC]] +(preinstalled on Mac OS X) or [[http://www.unixodbc.org/ unixODBC]. On +Linux, use your distribution's package management system to install the +necessary libraries and header files. For example, on Ubuntu, type + + $ sudo apt-get install libiodbc2 libiodbc2-dev +---- + +to install the iODBC library and header files. + +The Data/ODBC and Data/MySQL Makefiles will search for the ODBC and +MySQL headers and libraries in various places. Nevertheless, the +Makefiles may not be able to find the headers and libraries. In this +case, please edit the Makefile in Data/ODBC and/or Data/MySQL +accordingly. + + +!MySQL Client + +The Data library requires the [[http://dev.mysql.com MySQL]] client +libraries and header files if you want to build the MySQL connector +(which is the default). On Windows platforms, use the MySQL client +installer to install the necessary files. On Unix/Linux platforms, use +the package management system of your choice to install the necessary +files. Alternatively, you can of course build MySQL yourself from +source. + + +!!Building On Windows + +Microsoft Visual Studio 7.1 (2003), 8.0 (2005), 9.0 (2008) or 10.0 +(2010) is required to build the POCO C++ Libraries on Windows platforms. +Solution and project files for all versions are included. For Visual +Studio 2008 and 2010, 64-bit (x64) builds are supported as well. +You can either build from within Visual Studio (<*Build->Batch +Build->Select All;Rebuild*>) or from the command line. To build from the +command line, start the Visual Studio .NET 2003/2005/2008/2010 Command +Prompt and go (<[cd]>) to the directory where you have extracted the POCO +C++ Libraries sources. Then, simply start the <*buildwin.cmd*> script and +pass as argument the version of visual studio (71, 80, 90 or 100). You +can customize what is being built by <*buildwin.cmd*> by passing appropriate +command line arguments to it. Call <*buildwin.cmd*> without arguments to see +what is available. + +To disable certain components (e.g., NetSSL_OpenSSL or Data/MySQL) from +the build, edit the text file named <*components*> in the distribution +root directory and remove the respective lines. + +Certain libraries, like NetSSL_OpenSSL, Crypto or Data/MySQL have +dependencies to other libraries. Since the build script does not know where to +find the necessary header files and import libraries, you have to either add +the header file paths to the <[INCLUDE]> environment variable and the +library path to the <[LIB]> environment variable, or you'll have to edit the +buildwin.cmd script, where these environment variables can be set as +well. + +In order to run the test suite and the samples, the top-most bin +directory containing the resulting shared libraries must be in the PATH +environment variable. + + +!!Building On Unix/Linux/Mac OS X + +For building on Unix platforms, the POCO C++ Libraries come with their +own build system. The build system is based on GNU Make 3.80 (or newer), +with the help from a few shell scripts. If you do not have GNU Make 3.80 +(or newer) installed on your machine, you will need to download it from +http://directory.fsf.org/devel/build/make.html and +build and install it prior to building the POCO C++ Libraries. + +You can check the version of GNU Make installed on your system with + + $ gmake --version +---- + +or + + $ make --version +---- + +Once you have GNU Make up and running, the rest is quite simple. +To extract the sources and build all libraries, testsuites and samples, simply + + $ gunzip poco-X.Y.tar.gz + $ tar -xf poco-X.Y.tar.gz + $ cd poco-X.Y.tar.gz + $ ./configure + $ gmake -s +---- + +See the configure script source for a list of possible options. +For starters, we recommend <[--no-tests]> and <[--no-samples]>, to reduce build times. +On a multicore or multiprocessor machine, use parallel makes to speed up +the build (<[make -j4]>). + +Once you have successfully built POCO, you can install it +to <*/usr/local*> (or another directory specified as parameter +to configure <[--prefix=]>): + + $ sudo gmake -s install +---- + +You can omit certain components from the build. For example, you might +want to omit Data/ODBC or Data/MySQL if you do not have the corresponding +third-party libraries (iodbc or unixodbc, mysqlclient) installed +on your system. To do this, use the <[--omit]> argument to configure: + + $ ./configure --omit=Data/ODBC,Data/MySQL +---- + +<*IMPORTANT: Make sure that the path to the build directory does not +contain symbolic links. Furthermore, on Mac OS X (or other systems +with case insensitive filesystems), make sure that the characters in +the path have the correct case. Otherwise you'll get an error saying +"Current working directory not under $PROJECT_BASE.".*> + + +!!Building On QNX Neutrino + +For QNX Neutrino, the Unix build system (see the instructions above) is used. +You can use the build system to cross-compile for a target platform on a +Solaris or Linux host. Unfortunately, the Cygwin-based Windows host +environment has some major quirks that prevent the build system from +working there. You can also use the build system on a self-hosted QNX +system. The default build configuration for QNX (found in +build/config/QNX) is for a self-hosted x86 platform. To specify another +target, edit the CCVER setting in the build configuration file. For +example, to compile for a PowerPC target, specify +CCVER=3.3.1,gcc_ntoppcbe. + +Service Pack 1 for QNX Neutrino 6.3 must be installed, otherwise compiling the +Foundation library will fail due to a problem with the <**> header in the +default (Dinkumware) C++ standard library. + +When building on QNX, you might want to disable NetSSL_OpenSSL, Crypto and +some Data connectors, unless you have the necessary third party components +available: + + $ ./configure --omit=NetSSL_OpenSSL,Crypto,Data/ODBC,Data/MySQL +---- + + +!!!Tutorials And Sample Code + +Introductory documentation consisting of various documents and tutorials +in the form of slide decks can be found at the +[[http://pocoproject.org/documentation/ POCO C++ Libraries +Documentation]] page. + +Sample applications demonstrating the various features of the POCO C++ +Libraries are delivered with the source code. Every library's source +code directory +has a <*samples*> directory containing various sample applications. + +When building the sample applications on platforms using the gmake-based +build system, please make sure that the environment variable +<[POCO_BASE]> contains +the path to the POCO C++ Libraries source tree root directory. + + +!!!Creating Your Own POCO-based Applications + +The best way to create your first POCO-based application is by copying +one of the sample projects and making the desired changes. Examine the +project files and Makefiles to see what compiler options must be set for +your specific platform. diff --git a/doc/99100-ReleaseNotes.page b/doc/99100-ReleaseNotes.page index f032e2546..1ac26c03f 100644 --- a/doc/99100-ReleaseNotes.page +++ b/doc/99100-ReleaseNotes.page @@ -49,6 +49,11 @@ AAAIntroduction for the samDesired argument of RegOpenKeyEx() or RegCreateKeyEx(). - improved Poco::BasicEvent::notify() performance by avoiding an unnecessary heap allocation. + - added additional well-known port numbers to Poco::URI: rtsp, sip, sips, xmpp. + - added Poco::Net::MediaType::matchesRange() + - improved invalid socket handling: a Poco::Net::InvalidSocketException is + now thrown instead of an assertion when an operation is attempted on a closed or + otherwise uninitialized socket. !!!Release 1.4.0