{"id":23054002,"url":"https://github.com/emcecs/ecs-object-client-windows-cpp","last_synced_at":"2025-04-03T04:40:46.319Z","repository":{"id":50578776,"uuid":"78774096","full_name":"EMCECS/ecs-object-client-windows-cpp","owner":"EMCECS","description":"S3 Object Client with ECS extensions for C++ applications on Windows","archived":false,"fork":false,"pushed_at":"2022-12-06T16:52:18.000Z","size":5312,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-02-08T18:45:42.686Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EMCECS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-12T18:22:44.000Z","updated_at":"2022-12-14T22:40:16.000Z","dependencies_parsed_at":"2023-01-23T16:46:10.661Z","dependency_job_id":null,"html_url":"https://github.com/EMCECS/ecs-object-client-windows-cpp","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMCECS%2Fecs-object-client-windows-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMCECS%2Fecs-object-client-windows-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMCECS%2Fecs-object-client-windows-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EMCECS%2Fecs-object-client-windows-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EMCECS","download_url":"https://codeload.github.com/EMCECS/ecs-object-client-windows-cpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246939177,"owners_count":20857916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-16T00:32:26.359Z","updated_at":"2025-04-03T04:40:46.300Z","avatar_url":"https://github.com/EMCECS.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ECS Object Client Windows C++\n\nECS Object Client Windows C++ is a native Windows ECS/S3 client. This library supports the following configuration options:\n- x64 or x86\n- DLL or static library\n- Unicode or Ansi support\n- MFC statically linked or MFC DLL\n\nIt supports the following features:\n- Round-robin load balancing\n- Proxy server\n- Send/receive throttling\n- ECS metadata search\n- Multi-part uploads\n- S3 Lifecycle rules\n- Bulk S3 object delete\n- ECS Administrative functions\n- Allow abort of long running functions\n- Support progress callback for long running functions\n\n## Overview\n\nA connection to ECS is established by creating an instance of CECSConnection.\nThe CECSConnection object is thread-safe and the same object can be used by\nmultiple threads, or a new CECSConnection object can be created for each thread.\n\nHere is sample code showing how to initialize a connection:\n```C++\n   CECSConnection Conn;\n   // Initialize library\n   ECSInitLib();\n   deque\u003cCString\u003e IPList;\n   // IPList is set to 1 or more entries containing either an IP address or hostname\n   // of an ECS node, or the load balancer for ECS\n   // if HTTPS is used, IP addresses are not allowed. The ECS Hostname matching the\n   // subject in the SSL certificate must be used.\n   IPList.push_back(L\"object.ecstestdrive.com\");      // use ECS Test Drive\n   Conn.SetIPList(IPList);\n\n   // set S3 object user credentials\n   Conn.SetS3KeyID(L\"user1\");\n   Conn.SetSecret(L\"*********\");\n\n   // in this example, we are using HTTPS\n   Conn.SetSSL(true);\n   // the standard port for S3/SSL is 9021, but ECS Test Drive uses a load balancer that uses port 443\n   Conn.SetPort(443);\n   // give our connection a name\n   Conn.SetHost(_T(\"ECS Test Drive\"));\n   // set the user agent that usually identifies the application and version\n   Conn.SetUserAgent(_T(\"TestApp/1.0\"));\n   // optionally set maximum retries and waiting time between retries\n   Conn.SetRetries(10, SECONDS(2), SECONDS(4));\n   // optionally set SSL protocols that will be allowed\n   Conn.SetHttpsProtocol(WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_2);\n```\n## Deploy with Vcpkg\n\nThis library is supported by Vcpkg.\n\nTo use with Vcpkg, go to github (https://github.com/Microsoft/vcpkg) and clone Vcpkg.\n\nFollow the instructions on installing and registering Vcpkg.\n\nRun one or more of the following commands to build and deploy the following different configurations:\n\nx64, dynamic DLL, dynamic MFC:\n\n`C:\\vcpkg\u003evcpkg install ecsutil:x64-windows`\n\nx64, static lib, static MFC:\n\n`C:\\vcpkg\u003evcpkg install ecsutil:x64-windows-static`\n\nx64, static lib, dynamic MFC:\n\n`C:\\vcpkg\u003evcpkg install ecsutil:x64-windows-static-md`\n\nx86, dynamic DLL, dynamic MFC:\n\n`C:\\vcpkg\u003evcpkg install ecsutil:x86-windows`\n\nx86, static lib, static MFC:\n\n`C:\\vcpkg\u003evcpkg install ecsutil:x86-windows-static`\n\nx86, static lib, dynamic MFC:\n\n`C:\\vcpkg\u003evcpkg install ecsutil:x86-windows-static-md`\n\n## CECSConnection::S3_ERROR\n\nAll requests return an error code of type S3_ERROR. The error consists of:\n* A WIN32 error code. This is generally a Winhttp error indicating that the HTTP connection failed.\nFor example: ERROR_WINHTTP_TIMEOUT or ERROR_WINHTTP_CONNECTION_ERROR.\n* A HTTP error code. If the TCP/IP connection does make it to the ECS, this\nfield returns the HTTP error code that was received.\n* A S3 error code (enum). Generally, if an HTTP error code is received, an S3 error should be returned\nto shed more light on the error.\n\nIn addition, there are additional fields that may contain additional information:\n* sS3Code: S3 error code (string)\n* sS3Resource: Resource associated with the error\n* sS3RequestID: Request ID associated with the error\n* sDetails: ECS Admin: additional details\n## Data Transfer Options\nCommands that involve sending or receiving data can specify the data in one of 2 ways:\n- An in-memory buffer to hold the data, or to receive the data. This is using the CBuffer class which manages the dynamic\nallocation of memory. This can be used for all commands, but only if the amount of data is limited and can easily fit in\nmemory.\n- If the data cannot fit in memory, certain commands can use CECSConnection::STREAM_CONTEXT. This consists of a memory queue\nthat is used to \"feed\" the data to ECS, or to receive the data from ECS. A separate thread needs to be created that will feed\nor consume the data on the queue. Examples of how this works are in FileSupport.cpp.\n\n## CECSConnection class Reference\n### Create\nCreate or overwrite an object on ECS. Contents can be initialized to either a memory pointer (pData) or a stream. Metadata can be initialized using pMDList.\nAll headers of the response to the PUT can be returned in pReq;\n```C++\n\tS3_ERROR Create(LPCTSTR pszPath, const void *pData = nullptr, DWORD dwLen = 0, const list\u003cHEADER_STRUCT\u003e *pMDList = nullptr, const CBuffer *pChecksum = nullptr, STREAM_CONTEXT *pStreamSend = nullptr, ULONGLONG ullTotalLen = 0ULL, LPCTSTR pIfNoneMatch = nullptr, list \u003cHEADER_REQ\u003e *pReq = nullptr);\n```\n### DeleteS3\nDelete a single object or multiple objects. A version ID can be specified to delete a non-current version.\n```C++\n   S3_ERROR DeleteS3(LPCTSTR pszPath, LPCTSTR pszVersionId = nullptr);\n\tS3_ERROR DeleteS3(const list\u003cS3_DELETE_ENTRY\u003e\u0026 PathList);\n```\n### Read\nReceive the data of the specified object. If the size can fit in memory, use RetData to receive the data. Otherwise use pStreamReceive to set up a stream.\n```C++\n\tS3_ERROR Read(LPCTSTR pszPath, ULONGLONG lwLen, ULONGLONG lwOffset, CBuffer\u0026 RetData, DWORD dwBufOffset = 0, STREAM_CONTEXT *pStreamReceive = nullptr, list\u003cHEADER_REQ\u003e *pRcvHeaders = nullptr, ULONGLONG *pullReturnedLength = nullptr);\n```\n### DirListing\nGet a folder listing of objects. This uses a delimiter of '/'.\n```C++\n\tS3_ERROR DirListing(LPCTSTR pszPath, DirEntryList_t\u0026 DirList, bool bSingle = false, DWORD *pdwGetECSRetention = nullptr, LPCTSTR pszObjName = nullptr);\n\tS3_ERROR DirListingS3Versions(LPCTSTR pszPath, DirEntryList_t\u0026 DirList, LPCTSTR pszObjName = nullptr);\n```\n### S3ServiceInformation\nGet owner information and bucket list.\n```C++\n\tS3_ERROR S3ServiceInformation(S3_SERVICE_INFO\u0026 ServiceInfo);\n```\n### UpdateMetadata\nMetadata write.\n```C++\n\tvoid WriteMetadataEntry(list\u003cHEADER_STRUCT\u003e\u0026 MDList, LPCTSTR pszTag, const CBuffer\u0026 Data);\n\tvoid WriteMetadataEntry(list\u003cHEADER_STRUCT\u003e\u0026 MDList, LPCTSTR pszTag, const CString\u0026 sStr);\n\tS3_ERROR UpdateMetadata(LPCTSTR pszPath, const list\u003cHEADER_STRUCT\u003e\u0026 MDList, const list\u003cCString\u003e *pDeleteTagParam = nullptr);\n```\n### ReadProperties\nGet system and user metadata for object.\n```C++\n\tS3_ERROR ReadProperties(LPCTSTR pszPath, S3_SYSTEM_METADATA\u0026 Properties, LPCTSTR pszVersionId = nullptr, list\u003cHEADER_STRUCT\u003e *pMDList = nullptr, list\u003cHEADER_REQ\u003e *pReq = nullptr);\n```\n### ReadACL, WriteACL\nACL functions.\n```C++\n\tS3_ERROR ReadACL(LPCTSTR pszPath, deque\u003cACL_ENTRY\u003e\u0026 Acls, LPCTSTR pszVersion = nullptr);\n\tS3_ERROR WriteACL(LPCTSTR pszPath, const deque\u003cACL_ENTRY\u003e\u0026 Acls, LPCTSTR pszVersion = nullptr);\n```\n### GenerateShareableURL\nCreate shareable URL for object.\n```C++\n\tCString GenerateShareableURL(LPCTSTR pszPath, SYSTEMTIME *pstExpire);\n```\n### Bucket Functions\nBucket Functions.\n```C++\n\tS3_ERROR CreateS3Bucket(LPCTSTR pszBucketName);\n\tS3_ERROR DeleteS3Bucket(LPCTSTR pszBucketName);\n\tS3_ERROR S3GetBucketVersioning(LPCTSTR pszBucket, E_S3_VERSIONING\u0026 Versioning);\n\tS3_ERROR S3PutBucketVersioning(LPCTSTR pszBucket, E_S3_VERSIONING Versioning);\n```\n### RenameS3\nRename simulation. S3 does not support rename, so this function will do a PUT/COPY then delete.\n```C++\n\tS3_ERROR RenameS3(LPCTSTR pszOldPath, LPCTSTR pszNewPath, LPCTSTR pszVersionId, bool bCopy, const list\u003cCECSConnection::HEADER_STRUCT\u003e *pMDList, const list\u003cCString\u003e *pDeleteTagParam = nullptr);\n```\n### DataNodeEndpointS3\nRetrieves the ECS version string, plus the list of IP addresses for all nodes.\n```C++\n\tS3_ERROR DataNodeEndpointS3(S3_ENDPOINT_INFO\u0026 Endpoint);\n```\n### Lifecycle Functions\nLifecycle Functions.\n```C++\n\tS3_ERROR S3GetLifecycle(LPCTSTR pszBucket, S3_LIFECYCLE_INFO\u0026 Lifecycle);\n\tS3_ERROR S3PutLifecycle(LPCTSTR pszBucket, const S3_LIFECYCLE_INFO\u0026 Lifecycle);\n\tS3_ERROR S3DeleteLifecycle(LPCTSTR pszBucket);\n```\n\n## License\n\nCopyright 2017 EMC Corporation.  All Rights Reserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femcecs%2Fecs-object-client-windows-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femcecs%2Fecs-object-client-windows-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femcecs%2Fecs-object-client-windows-cpp/lists"}