---
title: "Developing IceBox Services"
url: https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services
language: cpp
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Developing IceBox Services

Programming language: C++. Other languages: [C#](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/php.md), [Python](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/swift.md).

## The IceBox `Service` Interface

Writing an IceBox service requires implementing the [IceBox Service](https://code.zeroc.com/ice/3.8/api/cpp/classIceBox_1_1Service.html) interface or abstract base class.

Your service implements two methods, `start` and `stop`. IceBox calls `start` after loading the service and `stop` when shutting down a running service. An administrator can also stop and restart the service through the [service manager](https://docs.zeroc.com/ice/3.8/services/icebox/icebox-administration.md). IceBox reuses the same service object, communicator, and arguments for each restart.

The `start` method initializes the service, typically by creating an object adapter and servants. The `name` and `args` parameters supply information from the service's [configuration](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/cpp.md), and the `communicator` parameter supplies a communicator that IceBox creates for the service. Services that [share a communicator](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/cpp.md) must use distinct names for their object adapters.

`start` must return once the service is initialized, because IceBox waits for it before starting the next service and before activating its admin object.

The `stop` method must release the resources owned by the service and destroy the [object adapters](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-activation-and-deactivation/cpp.md) it created.

IceBox owns the communicator it passes to `start` and destroys it when the server shuts down.

## IceBox Service Example

The example we present here is taken from the `IceBox/greeter` demo program.

The class definition for our service is quite straightforward:

```cpp
#include <IceBox/IceBox.h>

namespace Service
{
    class GreeterService final : public IceBox::Service
    {
    public:
        void start(
            const std::string& name,
            const Ice::CommunicatorPtr& communicator,
            const Ice::StringSeq& args) final;

        void stop() final;

    private:
        Ice::ObjectAdapterPtr _adapter;
    };
}
```

The implementation is equally straightforward:

```cpp
void
Service::GreeterService::start(
    [[maybe_unused]] const string& name,
    const Ice::CommunicatorPtr& communicator,
    [[maybe_unused]] const Ice::StringSeq& args)
{
    assert(!_adapter);
    _adapter = communicator->createObjectAdapterWithEndpoints(
        "GreeterAdapter",
        "tcp -p 4061");

    _adapter->add(
        make_shared<GreeterServer::Chatbot>("Syd"),
        Ice::Identity{"greeter"});

    _adapter->activate();
    cout << "Listening on port 4061..." << endl;
}

void
Service::GreeterService::stop()
{
    cout << "Shutting down..." << endl;

    assert(_adapter);
    _adapter->destroy();
    _adapter = nullptr;
}
```

The `start` method creates an object adapter “GreeterAdapter”, activates a single servant of type `Chatbot` (not shown), and activates the object adapter. The `stop` method simply destroys the object adapter.

### C++ Service Entry Point

The last piece of the puzzle is the *entry point* function, which the IceBox server calls to create an instance of the IceBox service:

```cpp
extern "C"
{
    ICE_DECLSPEC_EXPORT IceBox::Service*
    create(const Ice::CommunicatorPtr&)
    {
        return new Service::GreeterService;
    }
}
```

In this example, the `create` function returns a new instance of the `GreeterService` service. The name of the function is not important, but it must have the signature shown above. In particular, the function must have C linkage, accept a single `const Ice::CommunicatorPtr&` parameter and return an `IceBox::Service*`.

[Configuring IceBox Services](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/cpp.md) provides more information on entry points and describes how to configure your service into an IceBox server.

## IceBox Service Failures

A service implementation can indicate a failure by throwing an exception. IceBox handles the exception according to when it occurs:

- **Initial startup** If the service's entry point or initial `start` call throws, the server terminates as described in [Starting the IceBox Server](https://docs.zeroc.com/ice/3.8/services/icebox/starting-the-icebox-server/cpp.md#icebox-server-failures).
- **Administrative start** If `start` throws during `ServiceManager.startService`, IceBox logs a warning, records the service as stopped, and returns normally from `startService`.
- **Administrative stop** If `stop` throws during `ServiceManager.stopService`, IceBox logs a warning, records the service as started, and returns normally from `stopService`.
- **Server shutdown** If `stop` throws, IceBox logs a warning and continues stopping the remaining services and destroying their communicators.

Because `startService` and `stopService` return normally in these cases, use `ServiceManager.isServiceRunning` to check whether the service started or stopped.

If `start` fails, the service must release resources it acquired during that attempt before propagating the exception. IceBox calls `stop` only for services it records as started.

## See Also

- [Configuring IceBox Services](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/cpp.md)
- [Starting the IceBox Server](https://docs.zeroc.com/ice/3.8/services/icebox/starting-the-icebox-server/cpp.md)
